diff --git a/include/base_screen.h b/include/base_screen.h index 83bbf5bf54..3668fca1b4 100644 --- a/include/base_screen.h +++ b/include/base_screen.h @@ -35,71 +35,10 @@ /** - * BASE_SCREEN - * handles how to draw a screen (a board, a schematic ...) + * Handles how to draw a screen (a board, a schematic ...) */ class BASE_SCREEN : public EDA_ITEM { -private: - bool m_flagModified; ///< Indicates current drawing has been modified. - bool m_flagSave; ///< Indicates automatic file save. - - /** - * The cross hair position in logical (drawing) units. The cross hair is not the cursor - * position. It is an addition indicator typically drawn on grid to indicate to the - * user where the current action will be performed. - */ - wxPoint m_crossHairPosition; - -protected: - /** - * The number of #BASE_SCREEN objects in this design. - * - * This currently only has meaning for #SCH_SCREEN objects because #PCB_SCREEN object - * are limited to a single file. The count is virtual because #SCH_SCREEN objects can be - * used more than once so the screen (page) count can be more than the number of screen - * objects. - */ - int m_pageCount; - - /** - * An integer based page number used for printing a range of pages. - * - * This page number is set before printing and plotting because page numbering does not - * reflect the actual page number in complex hiearachies in #SCH_SCREEN objects. - */ - int m_virtualPageNumber; - - /** - * A user defined string page number used for printing and plotting. - * - * This currently only has meaning for #SCH_SCREEN objects because #PCB_SCREEN object - * are limited to a single file. This must be set before displaying, printing, or - * plotting the current sheet. If empty, the #m_virtualPageNumber value is converted - * to a string. - */ - wxString m_pageNumber; - -public: - static wxString m_PageLayoutDescrFileName; ///< the name of the page layout descr file, - ///< or emty to used the default pagelayout - - wxPoint m_DrawOrg; ///< offsets for drawing the circuit on the screen - - VECTOR2D m_LocalOrigin; ///< Relative Screen cursor coordinate (on grid) - ///< in user units. (coordinates from last reset position) - - wxPoint m_StartVisu; ///< Coordinates in drawing units of the current - ///< view position (upper left corner of device) - - bool m_Center; ///< Center on screen. If true (0.0) is centered on screen - ///< coordinates can be < 0 and > 0 except for schematics. - ///< false: when coordinates can only be >= 0 (schematics). - - VECTOR2D m_ScrollCenter; ///< Current scroll center point in logical units. - - bool m_Initialized; - public: BASE_SCREEN( EDA_ITEM* aParent, KICAD_T aType = SCREEN_T ); @@ -142,9 +81,69 @@ public: const wxString& GetPageNumber() const; void SetPageNumber( const wxString& aPageNumber ) { m_pageNumber = aPageNumber; } + #if defined(DEBUG) void Show( int nestLevel, std::ostream& os ) const override; #endif + + static wxString m_PageLayoutDescrFileName; ///< the name of the page layout descr file, + ///< or emty to used the default pagelayout + + wxPoint m_DrawOrg; ///< offsets for drawing the circuit on the screen + + VECTOR2D m_LocalOrigin; ///< Relative Screen cursor coordinate (on grid) + ///< in user units. (coordinates from last reset position) + + wxPoint m_StartVisu; ///< Coordinates in drawing units of the current + ///< view position (upper left corner of device) + + bool m_Center; ///< Center on screen. If true (0.0) is centered on screen + ///< coordinates can be < 0 and > 0 except for schematics. + ///< false: when coordinates can only be >= 0 (schematics). + + VECTOR2D m_ScrollCenter; ///< Current scroll center point in logical units. + + bool m_Initialized; + +protected: + /** + * The number of #BASE_SCREEN objects in this design. + * + * This currently only has meaning for #SCH_SCREEN objects because #PCB_SCREEN object + * are limited to a single file. The count is virtual because #SCH_SCREEN objects can be + * used more than once so the screen (page) count can be more than the number of screen + * objects. + */ + int m_pageCount; + + /** + * An integer based page number used for printing a range of pages. + * + * This page number is set before printing and plotting because page numbering does not + * reflect the actual page number in complex hiearachies in #SCH_SCREEN objects. + */ + int m_virtualPageNumber; + + /** + * A user defined string page number used for printing and plotting. + * + * This currently only has meaning for #SCH_SCREEN objects because #PCB_SCREEN object + * are limited to a single file. This must be set before displaying, printing, or + * plotting the current sheet. If empty, the #m_virtualPageNumber value is converted + * to a string. + */ + wxString m_pageNumber; + +private: + bool m_flagModified; ///< Indicates current drawing has been modified. + bool m_flagSave; ///< Indicates automatic file save. + + /** + * The cross hair position in logical (drawing) units. The cross hair is not the cursor + * position. It is an addition indicator typically drawn on grid to indicate to the + * user where the current action will be performed. + */ + wxPoint m_crossHairPosition; }; #endif // BASE_SCREEN_H diff --git a/include/basic_gal.h b/include/basic_gal.h index 1dc4151423..287856c400 100644 --- a/include/basic_gal.h +++ b/include/basic_gal.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2016 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 1992-2017 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -35,8 +35,8 @@ class PLOTTER; /* - * BASIC_GAL is a minimal GAL implementation to draw, plot and convert - * stroke texts to a set of segments for DRC tests, and to calculate text sizes. + * A minimal GAL implementation to draw, plot and convert stroke texts to a set of segments + * for DRC tests, and to calculate text sizes. * * Currently it allows one to use GAL and STROKE_FONT methods in legacy draw mode * (using wxDC functions) in plot functions only for texts. @@ -56,24 +56,17 @@ struct TRANSFORM_PRM // A helper class to transform coordinates in BASIC_GAL double m_rotAngle; }; + class BASIC_GAL: public KIGFX::GAL { -public: - wxDC* m_DC; - COLOR4D m_Color; - -private: - TRANSFORM_PRM m_transform; - std::stack m_transformHistory; - public: BASIC_GAL( KIGFX::GAL_DISPLAY_OPTIONS& aDisplayOptions ) : GAL( aDisplayOptions ) { - m_DC = NULL; + m_DC = nullptr; m_Color = RED; - m_plotter = NULL; - m_callback = NULL; + m_plotter = nullptr; + m_callback = nullptr; m_callbackData = nullptr; m_isClipped = false; } @@ -83,7 +76,8 @@ public: m_plotter = aPlotter; } - void SetCallback( void (* aCallback)( int x0, int y0, int xf, int yf, void* aData ), void* aData ) + void SetCallback( void (* aCallback)( int x0, int y0, int xf, int yf, void* aData ), + void* aData ) { m_callback = aCallback; m_callbackData = aData; @@ -93,13 +87,13 @@ public: /// If NULL, no clip will be made void SetClipBox( EDA_RECT* aClipBox ) { - m_isClipped = aClipBox != NULL; + m_isClipped = aClipBox != nullptr; if( aClipBox ) m_clipBox = *aClipBox; } - /// @brief Save the context. + /// Save the context. virtual void Save() override { m_transformHistory.push( m_transform ); @@ -112,21 +106,24 @@ public: } /** - * @brief Draw a polyline + * Draw a polyline + * * @param aPointList is a list of 2D-Vectors containing the polyline points. */ virtual void DrawPolyline( const std::deque& aPointList ) override; virtual void DrawPolyline( const VECTOR2D aPointList[], int aListSize ) override; - /** Start and end points are defined as 2D-Vectors. + /** + * Start and end points are defined as 2D-Vectors. + * * @param aStartPoint is the start point of the line. * @param aEndPoint is the end point of the line. */ virtual void DrawLine( const VECTOR2D& aStartPoint, const VECTOR2D& aEndPoint ) override; /** - * @brief Translate the context. + * Translate the context. * * @param aTranslation is the translation vector. */ @@ -136,7 +133,7 @@ public: } /** - * @brief Rotate the context. + * Rotate the context. * * @param aAngle is the rotation angle in radians. */ @@ -152,6 +149,14 @@ private: // Apply the roation/translation transform to aPoint const VECTOR2D transform( const VECTOR2D& aPoint ) const; +public: + wxDC* m_DC; + COLOR4D m_Color; + +private: + TRANSFORM_PRM m_transform; + std::stack m_transformHistory; + // A clip box, to clip drawings in a wxDC (mandatory to avoid draw issues) EDA_RECT m_clipBox; // The clip box bool m_isClipped; // Allows/disallows clipping @@ -162,8 +167,7 @@ private: void (* m_callback)( int x0, int y0, int xf, int yf, void* aData ); void* m_callbackData; // a optional parameter for m_callback - // When calling the draw functions for plot, the plotter acts as a wxDC - // to plot basic items + // When calling the draw functions for plot, the plotter acts as a wxDC to plot basic items. PLOTTER* m_plotter; }; diff --git a/include/bin_mod.h b/include/bin_mod.h index 0ae964a62f..338a7510c9 100644 --- a/include/bin_mod.h +++ b/include/bin_mod.h @@ -1,7 +1,7 @@ /* * This program source code file is part of KiCad, a free EDA CAD application. * - * Copyright (C) 2014 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2014-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -24,6 +24,7 @@ #ifndef BIN_MOD_H_ #define BIN_MOD_H_ +/// @todo Should this be a check for the wxWidgets version rather that `#if 0`. #if 0 #include // wx 3.0: #else @@ -38,12 +39,11 @@ class APP_SETTINGS_BASE; /** - * Struct BIN_MOD - * pertains to a single program module, either an EXE or a DSO/DLL ("bin_mod"). + * Pertains to a single program module, either an EXE or a DSO/DLL ("bin_mod"). + * * It manages miscellaneous configuration file information pertinent to one bin_mod. - * Because it serves in both DSO/DLLs and in EXEs, its name is neutral. - *

- * Accessors are in containing (wrapper) classes. + * Because it serves in both DSO/DLLs and in EXEs, its name is neutral. Accessors are + * in containing (wrapper) classes. */ struct BIN_MOD { @@ -54,8 +54,9 @@ struct BIN_MOD void End(); /** - * Takes ownership of a new application settings object - * @param aPtr is the settings object for this module + * Takes ownership of a new application settings object. + * + * @param aPtr is the settings object for this module. */ void InitSettings( APP_SETTINGS_BASE* aPtr ) { m_config = aPtr; } @@ -65,8 +66,6 @@ struct BIN_MOD wxString m_help_file; SEARCH_STACK m_search; - - }; #endif // BIN_MOD_H_ diff --git a/include/bitmap_base.h b/include/bitmap_base.h index 11ff67ee21..c697f99587 100644 --- a/include/bitmap_base.h +++ b/include/bitmap_base.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2018 jean-pierre.charras jp.charras at wanadoo.fr - * Copyright (C) 2013-2018 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2013-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -41,27 +41,15 @@ class PLOTTER; /** * This class handle bitmap images in KiCad. - * It is not intended to be used alone, but inside another class, - * so all methods are protected ( or private ) - * It is used in SCH_BITMAP class and WS_DRAW_ITEM_BITMAP (and other in future) * - * Remember not all plotters are able to plot a bitmap - * Mainly GERBER plotters cannot. + * It is not intended to be used alone, but inside another class so all methods are protected + * or private. It is used in #SCH_BITMAP class, #WS_DRAW_ITEM_BITMAP, and possibly others in + * the future. + * + * @warning Not all plotters are able to plot a bitmap. Mainly GERBER plotters cannot. */ class BITMAP_BASE { -private: - double m_scale; // The scaling factor of the bitmap - // With m_pixelSizeIu, controls the actual draw size - wxImage* m_image; // the raw image data (png format) - wxBitmap* m_bitmap; // the bitmap used to draw/plot image - double m_pixelSizeIu; // The scaling factor of the bitmap - // to convert the bitmap size (in pixels) - // to internal KiCad units - // Usually does not change - int m_ppi; // the bitmap definition. the default is 300PPI - - public: BITMAP_BASE( const wxPoint& pos = wxPoint( 0, 0 ) ); @@ -73,7 +61,6 @@ public: delete m_image; } - /* * Accessors: */ @@ -93,9 +80,9 @@ public: void SetScale( double aScale ) { m_scale = aScale; } /* - * Function RebuildBitmap - * Rebuild the internal bitmap used to draw/plot image - * must be called after a m_image change + * Rebuild the internal bitmap used to draw/plot image. + * + * This must be called after a #m_image change. */ void RebuildBitmap() { *m_bitmap = wxBitmap( *m_image ); } @@ -106,36 +93,32 @@ public: } /** - * Function ImportData - * Copy aItem image to me and update m_bitmap + * Copy aItem image to this object and update #m_bitmap. */ void ImportData( BITMAP_BASE* aItem ); /** - * Function GetScalingFactor - * @return the scaling factor from pixel size to actual draw size - * this scaling factor depends on m_pixelSizeIu and m_scale - * m_pixelSizeIu gives the scaling factor between a pixel size and - * the internal schematic units - * m_scale is an user dependant value, and gives the "zoom" value - * m_scale = 1.0 = original size of bitmap. - * m_scale < 1.0 = the bitmap is drawn smaller than its original size. - * m_scale > 1.0 = the bitmap is drawn bigger than its original size. + * This scaling factor depends on #m_pixelSizeIu and #m_scale. + * + * #m_pixelSizeIu gives the scaling factor between a pixel size and the internal units. + * #m_scale is an user dependent value, and gives the "zoom" value. + * - #m_scale = 1.0 = original size of bitmap. + * - #m_scale < 1.0 = the bitmap is drawn smaller than its original size. + * - #m_scale > 1.0 = the bitmap is drawn bigger than its original size. + * + * @return The scaling factor from pixel size to actual draw size. */ double GetScalingFactor() const { return m_pixelSizeIu * m_scale; } - /** - * Function GetSize * @return the actual size (in user units, not in pixels) of the image */ wxSize GetSize() const; /** - * Function GetSizePixels * @return the size in pixels of the image */ wxSize GetSizePixels() const @@ -147,8 +130,7 @@ public: } /** - * @return the bitmap definition in ppi - * the default is 300 ppi + * @return the bitmap definition in ppi, the default is 300 ppi. */ int GetPPI() const { @@ -156,12 +138,11 @@ public: } /** - * Function GetBoundingBox - * returns the orthogonal, bounding box of this object for display - * purposes. This box should be an enclosing perimeter for visible - * components of this object, and the units should be in the pcb or - * schematic coordinate system. It is OK to overestimate the size - * by a few counts. + * Return the orthogonal, bounding box of this object for display purposes. + * + * This box should be an enclosing perimeter for visible components of this object, + * and the units should be in the pcb or schematic coordinate system. It is OK to + * overestimate the size by a few counts. */ const EDA_RECT GetBoundingBox() const; @@ -170,83 +151,98 @@ public: /** * Reads and stores in memory an image file. * - * Init the bitmap format used to draw this item. - * supported images formats are format supported by wxImage - * if all handlers are loaded - * by default, .png, .jpeg are always loaded + * Initialize the bitmap format used to draw this item. Supported images formats are + * format supported by wxImage if all handlers are loaded. By default, .png, .jpeg + * are always loaded. * * @param aFullFilename The full filename of the image file to read. - * @return bool - true if success reading else false. + * @return true if success reading else false. */ bool ReadImageFile( const wxString& aFullFilename ); /** * Reads and stores in memory an image file. * - * Init the bitmap format used to draw this item. - * supported images formats are format supported by wxImage - * if all handlers are loaded - * by default, .png, .jpeg are always loaded + * Initialize the bitmap format used to draw this item. * - * @param aInStream an input stream containing the file data - * @return bool - true if success reading else false. + * Supported images formats are format supported by wxImage if all handlers are loaded. + * By default, .png, .jpeg are always loaded. + * + * @param aInStream an input stream containing the file data. + * @return true if success reading else false. */ bool ReadImageFile( wxInputStream& aInStream ); /** - * writes the bitmap data to aFile - * The format is png, in Hexadecimal form: - * If the hexadecimal data is converted to binary it gives exactly a .png image data + * Write the bitmap data to \a aFile. + * + * The file format is png, in hexadecimal form. If the hexadecimal data is converted to + * binary it gives exactly a .png image data. + * * @param aFile The FILE to write to. - * @return bool - true if success writing else false. + * @return true if success writing else false. */ bool SaveData( FILE* aFile ) const; /** - * writes the bitmap data to an array string - * The format is png, in Hexadecimal form: - * If the hexadecimal data is converted to binary it gives exactly a .png image data + * Write the bitmap data to an array string. + * + * The format is png, in Hexadecimal form. If the hexadecimal data is converted to binary + * it gives exactly a .png image data. + * * @param aPngStrings The wxArrayString to write to. */ void SaveData( wxArrayString& aPngStrings ) const; /** - * Load an image data saved by SaveData (png, in Hexadecimal form) - * @param aLine - the LINE_READER used to read the data file. - * @param aErrorMsg - Description of the error if an error occurs while loading the - * png bimap data. + * Load an image data saved by #SaveData. + * + * The file format must be png format in hexadecimal. + * + * @param aLine the LINE_READER used to read the data file. + * @param aErrorMsg Description of the error if an error occurs while loading the + * png bitmap data. * @return true if the bitmap loaded successfully. */ bool LoadData( LINE_READER& aLine, wxString& aErrorMsg ); - /** - * Function Mirror - * Mirror image vertically (i.e. relative to its horizontal X axis ) - * or horizontally (i.e relative to its vertical Y axis) - * @param aVertically = false to mirror horizontally - * or true to mirror vertically + * Mirror image vertically (i.e. relative to its horizontal X axis ) or horizontally (i.e + * relative to its vertical Y axis). + * @param aVertically false to mirror horizontally or true to mirror vertically. */ void Mirror( bool aVertically ); /** - * Function Rotate * Rotate image CW or CCW. - * @param aRotateCCW = true to rotate CCW + * + * @param aRotateCCW true to rotate CCW or false to rotate CW. */ void Rotate( bool aRotateCCW ); /** - * Function PlotImage * Plot bitmap on plotter. + * * If the plotter does not support bitmaps, plot a - * @param aPlotter = the plotter to use - * @param aPos = the position od the center of the bitmap - * @param aDefaultColor = the color used to plot the rectangle when bitmap is not supported - * @param aDefaultPensize = the pen size used to plot the rectangle when bitmap is not supported + * + * @param aPlotter the plotter to use. + * @param aPos the position of the center of the bitmap. + * @param aDefaultColor the color used to plot the rectangle when bitmap is not supported. + * @param aDefaultPensize the pen size used to plot the rectangle when bitmap is not supported. */ void PlotImage( PLOTTER* aPlotter, const wxPoint& aPos, KIGFX::COLOR4D aDefaultColor, int aDefaultPensize ); + +private: + double m_scale; // The scaling factor of the bitmap + // With m_pixelSizeIu, controls the actual draw size + wxImage* m_image; // the raw image data (png format) + wxBitmap* m_bitmap; // the bitmap used to draw/plot image + double m_pixelSizeIu; // The scaling factor of the bitmap + // to convert the bitmap size (in pixels) + // to internal KiCad units + // Usually does not change + int m_ppi; // the bitmap definition. the default is 300PPI }; diff --git a/include/board_design_settings.h b/include/board_design_settings.h index ee2ffeb04e..895aa150a5 100644 --- a/include/board_design_settings.h +++ b/include/board_design_settings.h @@ -96,9 +96,8 @@ /** - * Struct VIA_DIMENSION - * is a small helper container to handle a stock of specific vias each with - * unique diameter and drill sizes in the BOARD class. + * Container to handle a stock of specific vias each with unique diameter and drill sizes + * in the #BOARD class. */ struct VIA_DIMENSION { @@ -133,9 +132,8 @@ struct VIA_DIMENSION /** - * Struct DIFF_PAIR_DIMENSION - * is a small helper container to handle a stock of specific differential pairs each with - * unique track width, gap and via gap. + * Container to handle a stock of specific differential pairs each with unique track width, + * gap and via gap. */ struct DIFF_PAIR_DIMENSION { @@ -215,11 +213,479 @@ enum class DIM_UNITS_MODE : int; /** - * BOARD_DESIGN_SETTINGS - * contains design settings for a BOARD object. + * Container for design settings for a #BOARD object. */ class BOARD_DESIGN_SETTINGS : public NESTED_SETTINGS { +public: + BOARD_DESIGN_SETTINGS( JSON_SETTINGS* aParent, const std::string& aPath ); + + virtual ~BOARD_DESIGN_SETTINGS(); + + BOARD_DESIGN_SETTINGS( const BOARD_DESIGN_SETTINGS& aOther); + + BOARD_DESIGN_SETTINGS& operator=( const BOARD_DESIGN_SETTINGS& aOther ); + + bool LoadFromFile( const wxString& aDirectory = "" ) override; + + BOARD_STACKUP& GetStackupDescriptor() { return m_stackup; } + + SEVERITY GetSeverity( int aDRCErrorCode ); + + /** + * Return true if the DRC error code's severity is SEVERITY_IGNORE. + */ + bool Ignore( int aDRCErrorCode ); + + NETCLASSES& GetNetClasses() const + { + return *m_netClasses; + } + + void SetNetClasses( NETCLASSES* aNetClasses ) + { + if( aNetClasses ) + m_netClasses = aNetClasses; + else + m_netClasses = &m_internalNetClasses; + } + + ZONE_SETTINGS& GetDefaultZoneSettings() + { + return m_defaultZoneSettings; + } + + void SetDefaultZoneSettings( const ZONE_SETTINGS& aSettings ) + { + m_defaultZoneSettings = aSettings; + } + + /** + * @return the default netclass. + */ + inline NETCLASS* GetDefault() const + { + return GetNetClasses().GetDefaultPtr(); + } + + /** + * @return the current net class name. + */ + inline const wxString& GetCurrentNetClassName() const + { + return m_currentNetClassName; + } + + /** + * Return true if netclass values should be used to obtain appropriate track width. + */ + inline bool UseNetClassTrack() const + { + return ( m_trackWidthIndex == 0 && !m_useCustomTrackVia ); + } + + /** + * Return true if netclass values should be used to obtain appropriate via size. + */ + inline bool UseNetClassVia() const + { + return ( m_viaSizeIndex == 0 && !m_useCustomTrackVia ); + } + + /** + * Return true if netclass values should be used to obtain appropriate diff pair dimensions. + */ + inline bool UseNetClassDiffPair() const + { + return ( m_diffPairIndex == 0 && !m_useCustomDiffPair ); + } + + /** + * @return the biggest clearance value found in NetClasses list. + */ + int GetBiggestClearanceValue(); + + /** + * @return the smallest clearance value found in NetClasses list. + */ + int GetSmallestClearanceValue(); + + /** + * @return the current micro via size that is the current netclass value. + */ + int GetCurrentMicroViaSize(); + + /** + * @return the current micro via drill that is the current netclass value. + */ + int GetCurrentMicroViaDrill(); + + /** + * @return the current track width list index. + */ + inline unsigned GetTrackWidthIndex() const { return m_trackWidthIndex; } + + /** + * Set the current track width list index to \a aIndex. + * + * @param aIndex is the track width list index. + */ + void SetTrackWidthIndex( unsigned aIndex ); + + /** + * @return the current track width according to the selected options + * ( using the default netclass value or a preset/custom value ) + * the default netclass is always in m_TrackWidthList[0] + */ + int GetCurrentTrackWidth() const; + + /** + * Sets custom width for track (i.e. not available in netclasses or preset list). + * + * To have it returned with GetCurrentTrackWidth() you need to enable custom track & + * via sizes with #UseCustomTrackViaSize(). + * + * @param aWidth is the new track width. + */ + inline void SetCustomTrackWidth( int aWidth ) + { + m_customTrackWidth = aWidth; + } + + /** + * @return Current custom width for a track. + */ + inline int GetCustomTrackWidth() const + { + return m_customTrackWidth; + } + + /** + * @return the current via size list index. + */ + inline unsigned GetViaSizeIndex() const + { + return m_viaSizeIndex; + } + + /** + * Set the current via size list index to \a aIndex. + * + * @param aIndex is the via size list index. + */ + void SetViaSizeIndex( unsigned aIndex ); + + /** + * @return the current via size, according to the selected options + * ( using the default netclass value or a preset/custom value ) + * the default netclass is always in m_TrackWidthList[0] + */ + int GetCurrentViaSize() const; + + /** + * Set custom size for via diameter (i.e. not available in netclasses or preset list). + * + * To have it returned with GetCurrentViaSize() you need to enable custom track & via sizes + * with #UseCustomTrackViaSize(). + * + * @param aSize is the new drill diameter. + */ + inline void SetCustomViaSize( int aSize ) + { + m_customViaSize.m_Diameter = aSize; + } + + /** + * @return Current custom size for the via diameter. + */ + inline int GetCustomViaSize() const + { + return m_customViaSize.m_Diameter; + } + + /** + * @return the current via size, according to the selected options + * ( using the default netclass value or a preset/custom value ) + * the default netclass is always in m_TrackWidthList[0]. + */ + int GetCurrentViaDrill() const; + + /** + * Sets custom size for via drill (i.e. not available in netclasses or preset list). + * + * To have it returned with GetCurrentViaDrill() you need to enable custom track & via + * sizes with #UseCustomTrackViaSize(). + * + * @param aDrill is the new drill size. + */ + inline void SetCustomViaDrill( int aDrill ) + { + m_customViaSize.m_Drill = aDrill; + } + + /** + * @return Current custom size for the via drill. + */ + inline int GetCustomViaDrill() const + { + return m_customViaSize.m_Drill; + } + + /** + * Enables/disables custom track/via size settings. + * + * If enabled, values set with #SetCustomTrackWidth(), #SetCustomViaSize(), + * and #SetCustomViaDrill() are used for newly created tracks and vias. + * + * @param aEnabled decides if custom settings should be used for new tracks/vias. + */ + inline void UseCustomTrackViaSize( bool aEnabled ) + { + m_useCustomTrackVia = aEnabled; + } + + /** + * @return True if custom sizes of tracks & vias are enabled, false otherwise. + */ + inline bool UseCustomTrackViaSize() const + { + return m_useCustomTrackVia; + } + + /** + * @return the current diff pair dimension list index. + */ + inline unsigned GetDiffPairIndex() const { return m_diffPairIndex; } + + /** + * @param aIndex is the diff pair dimensions list index to set. + */ + void SetDiffPairIndex( unsigned aIndex ); + + /** + * Sets custom track width for differential pairs (i.e. not available in netclasses or + * preset list). + * + * @param aDrill is the new track wdith. + */ + inline void SetCustomDiffPairWidth( int aWidth ) + { + m_customDiffPair.m_Width = aWidth; + } + + /** + * @return Current custom track width for differential pairs. + */ + inline int GetCustomDiffPairWidth() + { + return m_customDiffPair.m_Width; + } + + /** + * Sets custom gap for differential pairs (i.e. not available in netclasses or preset + * list). + * @param aGap is the new gap. + */ + inline void SetCustomDiffPairGap( int aGap ) + { + m_customDiffPair.m_Gap = aGap; + } + + /** + * Function GetCustomDiffPairGap + * @return Current custom gap width for differential pairs. + */ + inline int GetCustomDiffPairGap() + { + return m_customDiffPair.m_Gap; + } + + /** + * Sets custom via gap for differential pairs (i.e. not available in netclasses or + * preset list). + * + * @param aGap is the new gap. Specify 0 to use the DiffPairGap for vias as well. + */ + inline void SetCustomDiffPairViaGap( int aGap ) + { + m_customDiffPair.m_ViaGap = aGap; + } + + /** + * @return Current custom via gap width for differential pairs. + */ + inline int GetCustomDiffPairViaGap() + { + return m_customDiffPair.m_ViaGap > 0 ? m_customDiffPair.m_ViaGap : m_customDiffPair.m_Gap; + } + + /** + * Enables/disables custom differential pair dimensions. + * + * @param aEnabled decides if custom settings should be used for new differential pairs. + */ + inline void UseCustomDiffPairDimensions( bool aEnabled ) + { + m_useCustomDiffPair = aEnabled; + } + + /** + * @return True if custom sizes of diff pairs are enabled, false otherwise. + */ + inline bool UseCustomDiffPairDimensions() const + { + return m_useCustomDiffPair; + } + + /** + * @return the current diff pair track width, according to the selected options + * ( using the default netclass value or a preset/custom value ) + * the default netclass is always in m_DiffPairDimensionsList[0]. + */ + inline int GetCurrentDiffPairWidth() const + { + if( m_useCustomDiffPair ) + return m_customDiffPair.m_Width; + else + return m_DiffPairDimensionsList[m_diffPairIndex].m_Width; + } + + /** + * @return the current diff pair gap, according to the selected options + * ( using the default netclass value or a preset/custom value ) + * the default netclass is always in m_DiffPairDimensionsList[0]. + */ + inline int GetCurrentDiffPairGap() const + { + if( m_useCustomDiffPair ) + return m_customDiffPair.m_Gap; + else + return m_DiffPairDimensionsList[m_diffPairIndex].m_Gap; + } + + /** + * @return the current diff pair via gap, according to the selected options + * ( using the default netclass value or a preset/custom value ) + * the default netclass is always in m_DiffPairDimensionsList[0]. + */ + inline int GetCurrentDiffPairViaGap() const + { + if( m_useCustomDiffPair ) + return m_customDiffPair.m_ViaGap; + else + return m_DiffPairDimensionsList[m_diffPairIndex].m_ViaGap; + } + + /** + * @param aValue The minimum distance between the edges of two holes or 0 to disable + * hole-to-hole separation checking. + */ + void SetMinHoleSeparation( int aDistance ); + + /** + * @param aValue The minimum distance between copper items and board edges. + */ + void SetCopperEdgeClearance( int aDistance ); + + /** + * Set the minimum distance between silk items to \a aValue. + * + * @note Compound graphics within a single footprint or on the board are not checked, + * but distances between text and between graphics from different footprints are. + * + * @param aValue The minimum distance between silk items. + */ + void SetSilkClearance( int aDistance ); + + /** + * Return a bit-mask of all the layers that are enabled. + * + * @return the enabled layers in bit-mapped form. + */ + inline LSET GetEnabledLayers() const + { + return m_enabledLayers; + } + + /** + * Change the bit-mask of enabled layers to \a aMask. + * + * @param aMask = The new bit-mask of enabled layers. + */ + void SetEnabledLayers( LSET aMask ); + + /** + * Test whether a given layer \a aLayerId is enabled. + * + * @param aLayerId The layer to be tested. + * @return true if the layer is enabled. + */ + inline bool IsLayerEnabled( PCB_LAYER_ID aLayerId ) const + { + if( aLayerId >= 0 && aLayerId < PCB_LAYER_ID_COUNT ) + return m_enabledLayers[aLayerId]; + + return false; + } + + /** + * @return the number of enabled copper layers. + */ + inline int GetCopperLayerCount() const + { + return m_copperLayerCount; + } + + /** + * Set the copper layer count to \a aNewLayerCount. + * + * @param aNewLayerCount The new number of enabled copper layers. + */ + void SetCopperLayerCount( int aNewLayerCount ); + + inline int GetBoardThickness() const { return m_boardThickness; } + inline void SetBoardThickness( int aThickness ) { m_boardThickness = aThickness; } + + /* + * Return an epsilon which accounts for rounding errors, etc. + * + * While currently an advanced cfg, going through this API allows us to easily change + * it to board-specific if so desired. + */ + int GetDRCEpsilon() const; + + /** + * Pad & via drills are finish size. + * + * Adding the hole plating thickness gives you the actual hole size. + */ + int GetHolePlatingThickness() const; + + /** + * Return the default graphic segment thickness from the layer class for the given layer. + */ + int GetLineThickness( PCB_LAYER_ID aLayer ) const; + + /** + * Return the default text size from the layer class for the given layer. + */ + wxSize GetTextSize( PCB_LAYER_ID aLayer ) const; + + /** + * Return the default text thickness from the layer class for the given layer. + */ + int GetTextThickness( PCB_LAYER_ID aLayer ) const; + + bool GetTextItalic( PCB_LAYER_ID aLayer ) const; + bool GetTextUpright( PCB_LAYER_ID aLayer ) const; + + int GetLayerClass( PCB_LAYER_ID aLayer ) const; + +private: + void initFromOther( const BOARD_DESIGN_SETTINGS& aOther ); + + bool migrateSchema0to1(); + public: // Note: the first value in each dimensions list is the current netclass value std::vector m_TrackWidthList; @@ -248,14 +714,15 @@ public: std::map m_DRCSeverities; // Map from DRCErrorCode to SEVERITY std::set m_DrcExclusions; - /* + /** * Option to select different fill algorithms. - * There are currenly two supported values: + * + * There are currently two supported values: * 5: * - Use thick outlines around filled polygons (gives smoothest shape but at the expense * of processing time and slight infidelity when exporting) * - Use zone outline when knocking out higher-priority zones (just wrong, but mimics - * legacy behaviour. + * legacy behavior. * 6: * - No thick outline. * - Use filled areas when knocking out higher-priority zones. @@ -275,7 +742,7 @@ public: int m_SolderMaskMinWidth; // Solder mask min width (2 areas closer than this // width are merged) int m_SolderPasteMargin; // Solder paste margin absolute value - double m_SolderPasteMarginRatio; // Solder pask margin ratio value of pad size + double m_SolderPasteMarginRatio; // Solder mask margin ratio value of pad size // The final margin is the sum of these 2 values // Variables used in footprint editing (default value in item/footprint creation) @@ -311,7 +778,7 @@ public: bool m_HasStackup; private: - // Indicies into the trackWidth, viaSizes and diffPairDimensions lists. + // Indices into the trackWidth, viaSizes and diffPairDimensions lists. // The 0 index is always the current netclass value(s) unsigned m_trackWidthIndex; unsigned m_viaSizeIndex; @@ -338,7 +805,7 @@ private: /** the description of layers stackup, for board fabrication * only physical layers are in layers stackup. - * It includes not only layers enabled for the board edition, but also dielectic layers + * It includes not only layers enabled for the board edition, but also dielectric layers */ BOARD_STACKUP m_stackup; @@ -348,505 +815,8 @@ private: /// This will point to m_internalNetClasses until it is repointed to the project after load NETCLASSES* m_netClasses; - /// The defualt settings that will be used for new zones + /// The default settings that will be used for new zones ZONE_SETTINGS m_defaultZoneSettings; - - void initFromOther( const BOARD_DESIGN_SETTINGS& aOther ); - - bool migrateSchema0to1(); - -public: - BOARD_DESIGN_SETTINGS( JSON_SETTINGS* aParent, const std::string& aPath ); - - virtual ~BOARD_DESIGN_SETTINGS(); - - BOARD_DESIGN_SETTINGS( const BOARD_DESIGN_SETTINGS& aOther); - - BOARD_DESIGN_SETTINGS& operator=( const BOARD_DESIGN_SETTINGS& aOther ); - - bool LoadFromFile( const wxString& aDirectory = "" ) override; - - BOARD_STACKUP& GetStackupDescriptor() { return m_stackup; } - - SEVERITY GetSeverity( int aDRCErrorCode ); - - /** - * returns true if the DRC error code's severity is SEVERITY_IGNORE - */ - bool Ignore( int aDRCErrorCode ); - - NETCLASSES& GetNetClasses() const - { - return *m_netClasses; - } - - void SetNetClasses( NETCLASSES* aNetClasses ) - { - if( aNetClasses ) - m_netClasses = aNetClasses; - else - m_netClasses = &m_internalNetClasses; - } - - ZONE_SETTINGS& GetDefaultZoneSettings() - { - return m_defaultZoneSettings; - } - - void SetDefaultZoneSettings( const ZONE_SETTINGS& aSettings ) - { - m_defaultZoneSettings = aSettings; - } - - /** - * Function GetDefault - * @return the default netclass. - */ - inline NETCLASS* GetDefault() const - { - return GetNetClasses().GetDefaultPtr(); - } - - /** - * Function GetCurrentNetClassName - * @return the current net class name. - */ - inline const wxString& GetCurrentNetClassName() const - { - return m_currentNetClassName; - } - - /** - * Function UseNetClassTrack - * returns true if netclass values should be used to obtain appropriate track width. - */ - inline bool UseNetClassTrack() const - { - return ( m_trackWidthIndex == 0 && !m_useCustomTrackVia ); - } - - /** - * Function UseNetClassVia - * returns true if netclass values should be used to obtain appropriate via size. - */ - inline bool UseNetClassVia() const - { - return ( m_viaSizeIndex == 0 && !m_useCustomTrackVia ); - } - - /** - * Function UseNetClassDiffPair - * returns true if netclass values should be used to obtain appropriate diff pair dimensions. - */ - inline bool UseNetClassDiffPair() const - { - return ( m_diffPairIndex == 0 && !m_useCustomDiffPair ); - } - - /** - * Function GetBiggestClearanceValue - * @return the biggest clearance value found in NetClasses list - */ - int GetBiggestClearanceValue(); - - /** - * Function GetSmallestClearanceValue - * @return the smallest clearance value found in NetClasses list - */ - int GetSmallestClearanceValue(); - - /** - * Function GetCurrentMicroViaSize - * @return the current micro via size, - * that is the current netclass value - */ - int GetCurrentMicroViaSize(); - - /** - * Function GetCurrentMicroViaDrill - * @return the current micro via drill, - * that is the current netclass value - */ - int GetCurrentMicroViaDrill(); - - /** - * Function GetTrackWidthIndex - * @return the current track width list index. - */ - inline unsigned GetTrackWidthIndex() const { return m_trackWidthIndex; } - - /** - * Function SetTrackWidthIndex - * sets the current track width list index to \a aIndex. - * - * @param aIndex is the track width list index. - */ - void SetTrackWidthIndex( unsigned aIndex ); - - /** - * Function GetCurrentTrackWidth - * @return the current track width, according to the selected options - * ( using the default netclass value or a preset/custom value ) - * the default netclass is always in m_TrackWidthList[0] - */ - int GetCurrentTrackWidth() const; - - /** - * Function SetCustomTrackWidth - * Sets custom width for track (i.e. not available in netclasses or preset list). To have - * it returned with GetCurrentTrackWidth() you need to enable custom track & via sizes - * (UseCustomTrackViaSize()). - * @param aWidth is the new track width. - */ - inline void SetCustomTrackWidth( int aWidth ) - { - m_customTrackWidth = aWidth; - } - - /** - * Function GetCustomTrackWidth - * @return Current custom width for a track. - */ - inline int GetCustomTrackWidth() const - { - return m_customTrackWidth; - } - - /** - * Function GetViaSizeIndex - * @return the current via size list index. - */ - inline unsigned GetViaSizeIndex() const - { - return m_viaSizeIndex; - } - - /** - * Function SetViaSizeIndex - * sets the current via size list index to \a aIndex. - * - * @param aIndex is the via size list index. - */ - void SetViaSizeIndex( unsigned aIndex ); - - /** - * Function GetCurrentViaSize - * @return the current via size, according to the selected options - * ( using the default netclass value or a preset/custom value ) - * the default netclass is always in m_TrackWidthList[0] - */ - int GetCurrentViaSize() const; - - /** - * Function SetCustomViaSize - * Sets custom size for via diameter (i.e. not available in netclasses or preset list). To have - * it returned with GetCurrentViaSize() you need to enable custom track & via sizes - * (UseCustomTrackViaSize()). - * @param aSize is the new drill diameter. - */ - inline void SetCustomViaSize( int aSize ) - { - m_customViaSize.m_Diameter = aSize; - } - - /** - * Function GetCustomViaSize - * @return Current custom size for the via diameter. - */ - inline int GetCustomViaSize() const - { - return m_customViaSize.m_Diameter; - } - - /** - * Function GetCurrentViaDrill - * @return the current via size, according to the selected options - * ( using the default netclass value or a preset/custom value ) - * the default netclass is always in m_TrackWidthList[0] - */ - int GetCurrentViaDrill() const; - - /** - * Function SetCustomViaDrill - * Sets custom size for via drill (i.e. not available in netclasses or preset list). To have - * it returned with GetCurrentViaDrill() you need to enable custom track & via sizes - * (UseCustomTrackViaSize()). - * @param aDrill is the new drill size. - */ - inline void SetCustomViaDrill( int aDrill ) - { - m_customViaSize.m_Drill = aDrill; - } - - /** - * Function GetCustomViaDrill - * @return Current custom size for the via drill. - */ - inline int GetCustomViaDrill() const - { - return m_customViaSize.m_Drill; - } - - /** - * Function UseCustomTrackViaSize - * Enables/disables custom track/via size settings. If enabled, values set with - * SetCustomTrackWidth()/SetCustomViaSize()/SetCustomViaDrill() are used for newly created - * tracks and vias. - * @param aEnabled decides if custom settings should be used for new tracks/vias. - */ - inline void UseCustomTrackViaSize( bool aEnabled ) - { - m_useCustomTrackVia = aEnabled; - } - - /** - * Function UseCustomTrackViaSize - * @return True if custom sizes of tracks & vias are enabled, false otherwise. - */ - inline bool UseCustomTrackViaSize() const - { - return m_useCustomTrackVia; - } - - /** - * Function GetDiffPairIndex - * @return the current diff pair dimension list index. - */ - inline unsigned GetDiffPairIndex() const { return m_diffPairIndex; } - - /** - * Function SetDiffPairIndex - * @param aIndex is the diff pair dimensions list index to set. - */ - void SetDiffPairIndex( unsigned aIndex ); - - /** - * Function SetCustomDiffPairWidth - * Sets custom track width for differential pairs (i.e. not available in netclasses or - * preset list). - * @param aDrill is the new track wdith. - */ - inline void SetCustomDiffPairWidth( int aWidth ) - { - m_customDiffPair.m_Width = aWidth; - } - - /** - * Function GetCustomDiffPairWidth - * @return Current custom track width for differential pairs. - */ - inline int GetCustomDiffPairWidth() - { - return m_customDiffPair.m_Width; - } - - /** - * Function SetCustomDiffPairGap - * Sets custom gap for differential pairs (i.e. not available in netclasses or preset - * list). - * @param aGap is the new gap. - */ - inline void SetCustomDiffPairGap( int aGap ) - { - m_customDiffPair.m_Gap = aGap; - } - - /** - * Function GetCustomDiffPairGap - * @return Current custom gap width for differential pairs. - */ - inline int GetCustomDiffPairGap() - { - return m_customDiffPair.m_Gap; - } - - /** - * Function SetCustomDiffPairViaGap - * Sets custom via gap for differential pairs (i.e. not available in netclasses or - * preset list). - * @param aGap is the new gap. Specify 0 to use the DiffPairGap for vias as well. - */ - inline void SetCustomDiffPairViaGap( int aGap ) - { - m_customDiffPair.m_ViaGap = aGap; - } - - /** - * Function GetCustomDiffPairViaGap - * @return Current custom via gap width for differential pairs. - */ - inline int GetCustomDiffPairViaGap() - { - return m_customDiffPair.m_ViaGap > 0 ? m_customDiffPair.m_ViaGap : m_customDiffPair.m_Gap; - } - - /** - * Function UseCustomDiffPairDimensions - * Enables/disables custom differential pair dimensions. - * @param aEnabled decides if custom settings should be used for new differential pairs. - */ - inline void UseCustomDiffPairDimensions( bool aEnabled ) - { - m_useCustomDiffPair = aEnabled; - } - - /** - * Function UseCustomDiffPairDimensions - * @return True if custom sizes of diff pairs are enabled, false otherwise. - */ - inline bool UseCustomDiffPairDimensions() const - { - return m_useCustomDiffPair; - } - - /** - * Function GetCurrentDiffPairWidth - * @return the current diff pair track width, according to the selected options - * ( using the default netclass value or a preset/custom value ) - * the default netclass is always in m_DiffPairDimensionsList[0] - */ - inline int GetCurrentDiffPairWidth() const - { - if( m_useCustomDiffPair ) - return m_customDiffPair.m_Width; - else - return m_DiffPairDimensionsList[m_diffPairIndex].m_Width; - } - - /** - * Function GetCurrentDiffPairGap - * @return the current diff pair gap, according to the selected options - * ( using the default netclass value or a preset/custom value ) - * the default netclass is always in m_DiffPairDimensionsList[0] - */ - inline int GetCurrentDiffPairGap() const - { - if( m_useCustomDiffPair ) - return m_customDiffPair.m_Gap; - else - return m_DiffPairDimensionsList[m_diffPairIndex].m_Gap; - } - - /** - * Function GetCurrentDiffPairViaGap - * @return the current diff pair via gap, according to the selected options - * ( using the default netclass value or a preset/custom value ) - * the default netclass is always in m_DiffPairDimensionsList[0] - */ - inline int GetCurrentDiffPairViaGap() const - { - if( m_useCustomDiffPair ) - return m_customDiffPair.m_ViaGap; - else - return m_DiffPairDimensionsList[m_diffPairIndex].m_ViaGap; - } - - /** - * Function SetMinHoleSeparation - * @param aValue The minimum distance between the edges of two holes or 0 to disable - * hole-to-hole separation checking. - */ - void SetMinHoleSeparation( int aDistance ); - - /** - * Function SetCopperEdgeClearance - * @param aValue The minimum distance between copper items and board edges. - */ - void SetCopperEdgeClearance( int aDistance ); - - /** - * Function SetSilkEdgeClearance - * @param aValue The minimum distance between silk items. Note that compound graphics - * within a single footprint or on the board are not checked, but distances between text - * and between graphics from different footprints are. - */ - void SetSilkClearance( int aDistance ); - - /** - * Function GetEnabledLayers - * returns a bit-mask of all the layers that are enabled - * @return int - the enabled layers in bit-mapped form. - */ - inline LSET GetEnabledLayers() const - { - return m_enabledLayers; - } - - /** - * Function SetEnabledLayers - * changes the bit-mask of enabled layers - * @param aMask = The new bit-mask of enabled layers - */ - void SetEnabledLayers( LSET aMask ); - - /** - * Function IsLayerEnabled - * tests whether a given layer is enabled - * @param aLayerId = The layer to be tested - * @return bool - true if the layer is enabled - */ - inline bool IsLayerEnabled( PCB_LAYER_ID aLayerId ) const - { - if( aLayerId >= 0 && aLayerId < PCB_LAYER_ID_COUNT ) - return m_enabledLayers[aLayerId]; - - return false; - } - - /** - * Function GetCopperLayerCount - * @return int - the number of neabled copper layers - */ - inline int GetCopperLayerCount() const - { - return m_copperLayerCount; - } - - /** - * Function SetCopperLayerCount - * do what its name says... - * @param aNewLayerCount = The new number of enabled copper layers - */ - void SetCopperLayerCount( int aNewLayerCount ); - - inline int GetBoardThickness() const { return m_boardThickness; } - inline void SetBoardThickness( int aThickness ) { m_boardThickness = aThickness; } - - /* - * Function GetDRCEpsilon - * an epsilon which accounts for rounding errors, etc. While currently an advanced cfg, - * going through this API allows us to easily change it to board-specific if so desired. - */ - int GetDRCEpsilon() const; - - /** - * Pad & via drills are finish size. Adding the hole plating thickness gives you the - * acutal hole size. - */ - int GetHolePlatingThickness() const; - - /** - * Function GetLineThickness - * Returns the default graphic segment thickness from the layer class for the given layer. - */ - int GetLineThickness( PCB_LAYER_ID aLayer ) const; - - /** - * Function GetTextSize - * Returns the default text size from the layer class for the given layer. - */ - wxSize GetTextSize( PCB_LAYER_ID aLayer ) const; - - /** - * Function GetTextThickness - * Returns the default text thickness from the layer class for the given layer. - */ - int GetTextThickness( PCB_LAYER_ID aLayer ) const; - - bool GetTextItalic( PCB_LAYER_ID aLayer ) const; - bool GetTextUpright( PCB_LAYER_ID aLayer ) const; - - int GetLayerClass( PCB_LAYER_ID aLayer ) const; }; #endif // BOARD_DESIGN_SETTINGS_H_ diff --git a/include/board_item.h b/include/board_item.h index c0f5ff076b..99f92c5299 100644 --- a/include/board_item.h +++ b/include/board_item.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wandadoo.fr - * Copyright (C) 1992-2016 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -43,9 +43,7 @@ class SHAPE; class PCB_GROUP; /** - * Enum PCB_SHAPE_TYPE_T - * is the set of shapes for PCB graphics and tracks and footprint graphics - * in the .m_Shape member + * The set of shapes for PCB graphics and tracks and footprint graphics in the .m_Shape member */ enum PCB_SHAPE_TYPE_T { @@ -77,18 +75,12 @@ static inline wxString PCB_SHAPE_TYPE_T_asString( PCB_SHAPE_TYPE_T a ) /** - * BOARD_ITEM - * is a base class for any item which can be embedded within the BOARD - * container class, and therefore instances of derived classes should only be - * found in Pcbnew or other programs that use class BOARD and its contents. - * The corresponding class in Eeschema is SCH_ITEM. + * A base class for any item which can be embedded within the #BOARD container class, and + * therefore instances of derived classes should only be found in Pcbnew or other programs + * that use class #BOARD and its contents. */ class BOARD_ITEM : public EDA_ITEM { -protected: - PCB_LAYER_ID m_layer; - PCB_GROUP* m_group; - public: BOARD_ITEM( BOARD_ITEM* aParent, KICAD_T idtype ) : EDA_ITEM( aParent, idtype ), @@ -115,11 +107,9 @@ public: } /** - * Function GetCenter() - * * This defaults to the center of the bounding box if not overridden. * - * @return centre point of the item + * @return center point of the item */ virtual wxPoint GetCenter() const { @@ -139,8 +129,8 @@ public: } /** - * Function IsConnected() * Returns information if the object is derived from BOARD_CONNECTED_ITEM. + * * @return True if the object is of BOARD_CONNECTED_ITEM type, false otherwise. */ virtual bool IsConnected() const @@ -162,12 +152,11 @@ public: static wxPoint ZeroOffset; /** - * Function GetEffectiveShape * Some pad shapes can be complex (rounded/chamfered rectangle), even without considering * custom shapes. This routine returns a COMPOUND shape (set of simple shapes which make - * up the pad fod use with routing, collision determiniation, etc). + * up the pad for use with routing, collision determination, etc). * - * Note that this list can contain a SHAPE_SIMPLE (a simple single-outline non-intersecting + * @note This list can contain a SHAPE_SIMPLE (a simple single-outline non-intersecting * polygon), but should never contain a SHAPE_POLY_SET (a complex polygon consisting of * multiple outlines and/or holes). * @@ -179,14 +168,12 @@ public: BOARD_ITEM_CONTAINER* GetParent() const { return (BOARD_ITEM_CONTAINER*) m_parent; } /** - * Function GetLayer - * returns the primary layer this item is on. + * Return the primary layer this item is on. */ virtual PCB_LAYER_ID GetLayer() const { return m_layer; } /** - * Function GetLayerSet - * returns a std::bitset of all layers on which the item physically resides. + * Return a std::bitset of all layers on which the item physically resides. */ virtual LSET GetLayerSet() const { return LSET( m_layer ); } virtual void SetLayerSet( LSET aLayers ) @@ -197,11 +184,12 @@ public: } /** - * Function SetLayer - * sets the layer this item is on. + * Set the layer this item is on. + * + * This method is virtual because some items (in fact: class DIMENSION) + * have a slightly different initialization. + * * @param aLayer The layer number. - * is virtual because some items (in fact: class DIMENSION) - * have a slightly different initialization */ virtual void SetLayer( PCB_LAYER_ID aLayer ) { @@ -209,8 +197,7 @@ public: } /** - * Function Duplicate - * creates a copy of a BOARD_ITEM. + * Create a copy of a of this #BOARD_ITEM. */ virtual BOARD_ITEM* Duplicate() const { @@ -221,20 +208,25 @@ public: } /** - * Swap data between aItem and aImage. - * aItem and aImage should have the same type - * Used in undo redo command to swap values between an item and its copy - * Only values like layer, size .. which are modified by editing are swapped - * @param aImage = the item image which contains data to swap + * Swap data between \a aItem and \a aImage. + * + * \a aItem and \a aImage should have the same type. + * + * Used in undo and redo commands to swap values between an item and its copy. + * Only values like layer, size .. which are modified by editing are swapped. + * + * @param aImage the item image which contains data to swap. */ virtual void SwapData( BOARD_ITEM* aImage ); /** - * Function IsOnLayer - * tests to see if this object is on the given layer. Virtual so objects like PAD, which - * reside on multiple layers can do their own form of testing. + * Test to see if this object is on the given layer. + * + * Virtual so objects like #PAD, which reside on multiple layers can do their own form + * of testing. + * * @param aLayer The layer to test for. - * @return bool - true if on given layer, else false. + * @return true if on given layer, else false. */ virtual bool IsOnLayer( PCB_LAYER_ID aLayer ) const { @@ -242,10 +234,9 @@ public: } /** - * Function IsTrack - * tests to see if this object is a track or via (or microvia). - * form of testing. - * @return bool - true if a track or via, else false. + * Test to see if this object is a track or via (or microvia). + * + * @return true if a track or via, else false. */ bool IsTrack() const { @@ -253,8 +244,7 @@ public: } /** - * Function IsLocked - * @return bool - true if the object is locked, else false + * @return true if the object is locked, else false. */ virtual bool IsLocked() const { @@ -263,8 +253,7 @@ public: } /** - * Function SetLocked - * modifies 'lock' status for of the item. + * Modify the 'lock' status for of the item. */ virtual void SetLocked( bool aLocked ) { @@ -272,22 +261,19 @@ public: } /** - * Function DeleteStructure - * deletes this object after removing from its parent if it has one. + * Delete this object after removing from its parent if it has one. */ void DeleteStructure(); /** - * Function ShowShape - * converts the enum PCB_SHAPE_TYPE_T integer value to a wxString. + * Convert the enum #PCB_SHAPE_TYPE_T integer value to a wxString. */ static wxString ShowShape( PCB_SHAPE_TYPE_T aShape ); - // Some geometric transforms, that must be rewritten for derived classes /** - * Function Move - * move this object. - * @param aMoveVector - the move vector for this object. + * Move this object. + * + * @param aMoveVector the move vector for this object. */ virtual void Move( const wxPoint& aMoveVector ) { @@ -301,10 +287,10 @@ public: } /** - * Function Rotate * Rotate this object. - * @param aRotCentre - the rotation point. - * @param aAngle - the rotation angle in 0.1 degree. + * + * @param aRotCentre the rotation point. + * @param aAngle the rotation angle in 0.1 degree. */ virtual void Rotate( const wxPoint& aRotCentre, double aAngle ) { @@ -317,10 +303,10 @@ public: } /** - * Function Flip - * Flip this object, i.e. change the board side for this object - * @param aCentre - the rotation point. - * @param aFlipLeftRight - mirror across Y axis instead of X (the default) + * Flip this object, i.e. change the board side for this object. + * + * @param aCentre the rotation point. + * @param aFlipLeftRight mirror across Y axis instead of X (the default). */ virtual void Flip( const wxPoint& aCentre, bool aFlipLeftRight ) { @@ -333,32 +319,30 @@ public: } /** - * Function GetBoard - * returns the BOARD in which this BOARD_ITEM resides, or NULL if none. + * Return the #BOARD in which this #BOARD_ITEM resides, or NULL if none. */ virtual BOARD* GetBoard() const; /** - * Function GetLayerName - * returns the name of the PCB layer on which the item resides. + * Return the name of the PCB layer on which the item resides. * - * @return wxString containing the layer name associated with this item. + * @return the layer name associated with this item. */ wxString GetLayerName() const; virtual void ViewGetLayers( int aLayers[], int& aCount ) const override; /** - * Function TransformShapeWithClearanceToPolygon - * Convert the item shape to a closed polygon - * Used in filling zones calculations - * Circles and arcs are approximated by segments - * @param aCornerBuffer = a buffer to store the polygon - * @param aClearanceValue = the clearance around the pad - * @param aError = the maximum deviation from true circle - * @param aErrorLoc = should the approximation error be placed outside or inside the polygon? - * @param ignoreLineWidth = used for edge cut items where the line width is only - * for visualization + * Convert the item shape to a closed polygon. + * + * Used in filling zones calculations. Circles and arcs are approximated by segments. + * + * @param aCornerBuffer a buffer to store the polygon. + * @param aClearanceValue the clearance around the pad. + * @param aError the maximum deviation from true circle. + * @param aErrorLoc should the approximation error be placed outside or inside the polygon? + * @param ignoreLineWidth used for edge cut items where the line width is only + * for visualization. */ virtual void TransformShapeWithClearanceToPolygon( SHAPE_POLY_SET& aCornerBuffer, PCB_LAYER_ID aLayer, int aClearanceValue, @@ -376,6 +360,9 @@ protected: * because layer names are customizable. */ virtual wxString layerMaskDescribe() const; + + PCB_LAYER_ID m_layer; + PCB_GROUP* m_group; }; #ifndef SWIG @@ -385,6 +372,7 @@ DECLARE_ENUM_TO_WXANY( PCB_LAYER_ID ); /** * A singleton item of this class is returned for a weak reference that no longer exists. + * * Its sole purpose is to flag the item as having been deleted. */ class DELETED_BOARD_ITEM : public BOARD_ITEM diff --git a/include/board_printout.h b/include/board_printout.h index 8a07efad07..faf02650ee 100644 --- a/include/board_printout.h +++ b/include/board_printout.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2009 Jean-Pierre Charras, jean-pierre.charras@ujf-grenoble.fr - * Copyright (C) 1992-2016 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * Copyright (C) 2018 CERN * Author: Maciej Suminski * @@ -62,16 +62,16 @@ struct BOARD_PRINTOUT_SETTINGS : public PRINTOUT_SETTINGS void Save( APP_SETTINGS_BASE* aConfig ) override; }; + /** - * BOARD_PRINTOUT - * is a class derived from wxPrintout to handle the necessary information to control a printer - * when printing a board + * An object derived from wxPrintout to handle the necessary information to control a printer + * when printing a board. */ class BOARD_PRINTOUT : public wxPrintout { public: BOARD_PRINTOUT( const BOARD_PRINTOUT_SETTINGS& aParams, const KIGFX::VIEW* aView, - const wxString& aTitle ); + const wxString& aTitle ); virtual ~BOARD_PRINTOUT() {} @@ -84,14 +84,16 @@ public: /** * Print a page (or a set of pages). - * Note: this function prepare print parameters for the function - * which actually print the draw layers. - * @param aLayerName = a text which can be printed as layer name - * @param aPageNum = the number of the current page (only used to print this value) - * @param aPageCount = the number of pages to ptint (only used to print this value) + * + * @note This function prepares the print parameters for the function which actually prints + * the draw layers. + * + * @param aLayerName a text which can be printed as layer name. + * @param aPageNum the number of the current page (only used to print this value). + * @param aPageCount the number of pages to ptint (only used to print this value). */ virtual void DrawPage( const wxString& aLayerName = wxEmptyString, - int aPageNum = 1, int aPageCount = 1 ); + int aPageNum = 1, int aPageCount = 1 ); protected: ///> Convert mils to internal units diff --git a/include/class_draw_panel_gal.h b/include/class_draw_panel_gal.h index a30bf14b74..80356a7549 100644 --- a/include/class_draw_panel_gal.h +++ b/include/class_draw_panel_gal.h @@ -77,7 +77,7 @@ public: * If \p aParentWindow is not an EDA frame, a search through all the parents * of the parent window will be done to find the frame. * - * @param aParentWindow is the window immeidately containing this panel + * @param aParentWindow is the window immediately containing this panel */ EDA_DRAW_PANEL_GAL( wxWindow* aParentWindow, wxWindowID aWindowId, const wxPoint& aPosition, const wxSize& aSize, @@ -88,36 +88,35 @@ public: virtual void SetFocus() override; /** - * Function SwitchBackend - * Switches method of rendering graphics. + * Switch method of rendering graphics. + * * @param aGalType is a type of rendering engine that you want to use. */ virtual bool SwitchBackend( GAL_TYPE aGalType ); /** - * Function GetBackend - * Returns the type of backend currently used by GAL canvas. + * Return the type of backend currently used by GAL canvas. */ inline GAL_TYPE GetBackend() const { return m_backend; } /** - * Function GetGAL() - * Returns a pointer to the GAL instance used in the panel. + * Return a pointer to the GAL instance used in the panel. + * * @return The instance of GAL. */ KIGFX::GAL* GetGAL() const { return m_gal; } /** - * Function GetView() - * Returns a pointer to the VIEW instance used in the panel. - * @return The instance of VIEW. + * Return a pointer to the #VIEW instance used in the panel. + * + * @return The instance of #VIEW. */ virtual KIGFX::VIEW* GetView() const { return m_view; } /** - * Function GetViewControls() - * Returns a pointer to the VIEW_CONTROLS instance used in the panel. - * @return The instance of VIEW_CONTROLS. + * Return a pointer to the #VIEW_CONTROLS instance used in the panel. + * + * @return The instance of #VIEW_CONTROLS. */ KIGFX::VIEW_CONTROLS* GetViewControls() const { @@ -128,42 +127,38 @@ public: virtual void Refresh( bool aEraseBackground = true, const wxRect* aRect = NULL ) override; /** - * Function ForceRefresh() - * Forces a redraw. + * Force a redraw. */ void ForceRefresh(); /** - * Function SetEventDispatcher() - * Sets a dispatcher that processes events and forwards them to tools. + * Set a dispatcher that processes events and forwards them to tools. + * + * #DRAW_PANEL_GAL does not take over the ownership. Passing NULL disconnects all event + * handlers from the #DRAW_PANEL_GAL and parent frame. + * * @param aEventDispatcher is the object that will be used for dispatching events. - * DRAW_PANEL_GAL does not take over the ownership. Passing NULL disconnects all event - * handlers from the DRAW_PANEL_GAL and parent frame. */ void SetEventDispatcher( TOOL_DISPATCHER* aEventDispatcher ); /** - * Function StartDrawing() - * Begins drawing if it was stopped previously. + * Begin drawing if it was stopped previously. */ void StartDrawing(); /** - * Function StopDrawing() - * Prevents the GAL canvas from further drawing till it is recreated - * or StartDrawing() is called. + * Prevent the GAL canvas from further drawing until it is recreated or #StartDrawing() + * is called. */ void StopDrawing(); /** - * Function SetHighContrastLayer - * Takes care of display settings for the given layer to be displayed in high contrast mode. + * Take care of display settings for the given layer to be displayed in high contrast mode. */ virtual void SetHighContrastLayer( int aLayer ); /** - * Function SetTopLayer - * Moves the selected layer to the top, so it is displayed above all others. + * Move the selected layer to the top, so it is displayed above all others. */ virtual void SetTopLayer( int aLayer ); @@ -173,37 +168,35 @@ public: } /** - * Function GetParentEDAFrame() - * Returns parent EDA_DRAW_FRAME, if available or NULL otherwise. + * Returns parent #EDA_DRAW_FRAME, if available or NULL otherwise. */ EDA_DRAW_FRAME* GetParentEDAFrame() const { return m_edaFrame; } bool IsDialogPreview() const { return m_parent != (wxWindow*) m_edaFrame; } /** - * Function OnShow() * Called when the window is shown for the first time. */ virtual void OnShow() {} /** - * Set whether focus is taken on certain events (mouseover, keys, etc). This should - * be true (and is by default) for any primary canvas, but can be false to make - * well-behaved preview panes and the like. + * Set whether focus is taken on certain events (mouseover, keys, etc). + * + * This should be true (and is by default) for any primary canvas, but can be false to make + * well behaved preview panes and the like. */ void SetStealsFocus( bool aStealsFocus ) { m_stealsFocus = aStealsFocus; } /** - * Function SetCurrentCursor - * Set the current cursor shape for this panel + * Set the current cursor shape for this panel. */ void SetCurrentCursor( KICURSOR cursor ); /** - * Returns the bounding box of the view that should be used if model is not valid + * Return the bounding box of the view that should be used if model is not valid. * For example, the worksheet bounding box for an empty PCB * - * @return the default bounding box for the panel + * @return the default bounding box for the panel. */ virtual BOX2I GetDefaultViewBBox() const { return BOX2I(); } @@ -214,25 +207,25 @@ public: /** * Repaint the canvas, and fix scrollbar cursors - * Usually called by a OnPaint event, but because it do not use a wxPaintDC, - * it can be called outside a wxPaintEvent. + * + * Usually called by a OnPaint event. + * + * Because it does not use a wxPaintDC, it can be called outside a wxPaintEvent. */ void DoRePaint(); /** - * Creates an overlay for rendering debug graphics. + * Create an overlay for rendering debug graphics. */ std::shared_ptr DebugOverlay(); /** - * Clears the contents of the debug overlay and removes it from the VIEW. + * Clear the contents of the debug overlay and removes it from the VIEW. */ void ClearDebugOverlay(); - protected: - virtual void onPaint( wxPaintEvent& WXUNUSED( aEvent ) ); void onSize( wxSizeEvent& aEvent ); void onEnter( wxMouseEvent& aEvent ); diff --git a/include/collector.h b/include/collector.h index 8733b2ef54..decdf81390 100644 --- a/include/collector.h +++ b/include/collector.h @@ -40,45 +40,29 @@ class EDA_ITEM; /** - * COLLECTOR - * is an abstract class that will find and hold all the objects according to + * An abstract class that will find and hold all the objects according to * an inspection done by the Inspect() function which must be implemented by - * any derived class. When Inspect() finds an object that it wants to collect, - * i.e. one that it "likes", then it only has to do an Append( testItem ) - * on it to add it to its collection, but in all cases for the scan to continue, - * Inspect() must return SEARCH_CONTINUE. + * any derived class. * - * Later, after collection, the user can iterate through all the objects - * in the remembered collection using GetCount() and the [int] operator. + * When Inspect() finds an object that it wants to collect, i.e. one that it "likes", then + * it only has to do an Append( testItem )on it to add it to its collection, but in all cases + * for the scan to continue, Inspect() must return SEARCH_CONTINUE. Later, after collection, + * the user can iterate through all the objects in the remembered collection using GetCount() + * and the [int] operator. */ class COLLECTOR { -protected: - std::vector m_list; // Primary list of most likely items - std::vector m_backupList; // Secondary list with items removed by heuristics - - const KICAD_T* m_scanTypes; - INSPECTOR_FUNC m_inspector; - wxPoint m_refPos; // Reference position used to generate the collection. - EDA_RECT m_refBox; // Selection rectangle used to generate the collection. - -public: - int m_Threshold; // Hit-test threshold in internal units. - - wxString m_MenuTitle; // The title of selection disambiguation menu (if needed) - bool m_MenuCancelled; // Indicates selection disambiguation menu was cancelled - public: COLLECTOR() : + m_Threshold( 0 ), + m_MenuCancelled( false ), m_scanTypes( 0 ), // Inspect() is virtual so calling it from a class common inspector preserves // polymorphism. m_inspector( [=]( EDA_ITEM* aItem, void* aTestData ) { return this->Inspect( aItem, aTestData ); - } ), - m_Threshold( 0 ), - m_MenuCancelled( false ) + } ) { } @@ -98,8 +82,7 @@ public: CITER end() const { return m_list.cend(); } /** - * Function GetCount - * returns the number of objects in the list + * Return the number of objects in the list. */ int GetCount() const { @@ -107,8 +90,7 @@ public: } /** - * Function Empty - * sets the list to empty + * Clear the list. */ void Empty() { @@ -116,8 +98,8 @@ public: } /** - * Function Append - * adds an item to the end of the list. + * Add an item to the end of the list. + * * @param item An EDA_ITEM* to add. */ void Append( EDA_ITEM* item ) @@ -126,8 +108,8 @@ public: } /** - * Function Remove - * removes the item at \a aIndex (first position is 0); + * Remove the item at \a aIndex (first position is 0). + * * @param aIndex The index into the list. */ void Remove( int aIndex ) @@ -136,8 +118,8 @@ public: } /** - * Function Remove - * removes the item aItem (if exists in the collector). + * Remove the item aItem (if exists in the collector). + * * @param aItem the item to be removed. */ void Remove( const EDA_ITEM* aItem ) @@ -151,8 +133,9 @@ public: } /** - * Test if the collector has heuristic backup items - * @return true if Combine() can run to bring secondary items into the list + * Test if the collector has heuristic backup items. + * + * @return true if Combine() can run to bring secondary items into the list. */ bool HasAdditionalItems() { @@ -160,7 +143,7 @@ public: } /** - * Re-combines the backup list into the main list of the collector + * Re-combine the backup list into the main list of the collector. */ void Combine() { @@ -169,7 +152,8 @@ public: } /** - * Moves the item at \a aIndex (first position is 0) to the backup list + * Move the item at \a aIndex (first position is 0) to the backup list. + * * @param aIndex The index into the list. */ void Transfer( int aIndex ) @@ -179,7 +163,8 @@ public: } /** - * Moves the item aItem (if exists in the collector) to the backup list + * Move \a aItem (if exists in the collector) to the backup list. + * * @param aItem the item to be moved. */ void Transfer( EDA_ITEM* aItem ) @@ -196,22 +181,21 @@ public: } /** - * Function operator[int] - * is used for read only access and returns the object at \a aIndex. + * Used for read only access and returns the object at \a aIndex. + * * @param aIndex The index into the list. - * @return EDA_ITEM* - or something derived from it, or NULL. + * @return the object at \a aIndex something derived from it or NULL. */ virtual EDA_ITEM* operator[]( int aIndex ) const { if( (unsigned)aIndex < (unsigned)GetCount() ) // (unsigned) excludes aIndex<0 also return m_list[ aIndex ]; - return NULL; + return nullptr; } /** - * Function HasItem - * tests if \a aItem has already been collected. + * Tests if \a aItem has already been collected. * * @param aItem The EDA_ITEM* to be tested. * @return True if \a aItem is already collected. @@ -228,9 +212,8 @@ public: } /** - * Function SetScanTypes - * records the list of KICAD_T types to consider for collection by - * the Inspect() function. + * Record the list of #KICAD_T types to consider for collection by the Inspect() function. + * * @param scanTypes An array of KICAD_T, terminated by EOT. No copy is * is made of this array (so cannot come from caller's stack). */ @@ -244,21 +227,37 @@ public: const EDA_RECT& GetBoundingBox() const { return m_refBox; } /** - * Function CountType - * counts the number of items matching aType - * @param aType type we are interested in - * @return number of occurences + * Count the number of items matching \a aType. + * + * @param aType type we are interested in. + * @return number of occurrences. */ int CountType( KICAD_T aType ) { int cnt = 0; + for( size_t i = 0; i < m_list.size(); i++ ) { if( m_list[i]->Type() == aType ) cnt++; } + return cnt; } + + int m_Threshold; // Hit-test threshold in internal units. + + wxString m_MenuTitle; // The title of selection disambiguation menu (if needed) + bool m_MenuCancelled; // Indicates selection disambiguation menu was canceled + +protected: + std::vector m_list; // Primary list of most likely items + std::vector m_backupList; // Secondary list with items removed by heuristics + + const KICAD_T* m_scanTypes; + INSPECTOR_FUNC m_inspector; + wxPoint m_refPos; // Reference position used to generate the collection. + EDA_RECT m_refBox; // Selection rectangle used to generate the collection.}; }; #endif // COLLECTOR_H diff --git a/include/commit.h b/include/commit.h index 4c1af90210..0e07790085 100644 --- a/include/commit.h +++ b/include/commit.h @@ -2,6 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright 2016-2017 CERN + * Copyright (C) 2020 KiCad Developers, see change_log.txt for contributors. * @author Tomasz Wlostowski * @author Maciej Suminski * @@ -60,10 +61,8 @@ CHANGE_TYPE operator&( CHANGE_TYPE aTypeA, T aTypeB ) /** - * COMMIT - * - * Represents a set of changes (additions, deletions or modifications) - * of a data model (e.g. the BOARD) class. + * Represent a set of changes (additions, deletions or modifications) of a data model + * (e.g. the BOARD) class. * * The class can be used to propagate changes to subscribed objects (e.g. views, ratsnest), * and automatically create undo/redo points. @@ -113,6 +112,7 @@ public: } template + COMMIT& StageItems( const Range& aRange, CHANGE_TYPE aChangeType ) { for( const auto& item : aRange ) @@ -121,19 +121,19 @@ public: return *this; } - ///> Adds a change of the item aItem of type aChangeType to the change list. virtual COMMIT& Stage( EDA_ITEM* aItem, CHANGE_TYPE aChangeType ); virtual COMMIT& Stage( std::vector& container, CHANGE_TYPE aChangeType ); - virtual COMMIT& Stage( const PICKED_ITEMS_LIST& aItems, UNDO_REDO aModFlag = UNDO_REDO::UNSPECIFIED ); + virtual COMMIT& Stage( const PICKED_ITEMS_LIST& aItems, + UNDO_REDO aModFlag = UNDO_REDO::UNSPECIFIED ); ///> Executes the changes. virtual void Push( const wxString& aMessage = wxT( "A commit" ), bool aCreateUndoEntry = true, bool aSetDirtyBit = true ) = 0; - ///> Revertes the commit by restoring the modifed items state. + ///> Revert the commit by restoring the modified items state. virtual void Revert() = 0; bool Empty() const @@ -161,10 +161,11 @@ protected: COMMIT& createModified( EDA_ITEM* aItem, EDA_ITEM* aCopy, int aExtraFlags = 0 ); - virtual void makeEntry( EDA_ITEM* aItem, CHANGE_TYPE aType, EDA_ITEM* aCopy = NULL ); + virtual void makeEntry( EDA_ITEM* aItem, CHANGE_TYPE aType, EDA_ITEM* aCopy = nullptr ); /** - * Searches for an entry describing change for a particular item + * Search for an entry describing change for a particular item. + * * @return null if there is no related entry. */ COMMIT_LINE* findEntry( EDA_ITEM* aItem ); diff --git a/include/common.h b/include/common.h index caf9b195a1..e568187504 100644 --- a/include/common.h +++ b/include/common.h @@ -56,16 +56,14 @@ class REPORTER; /** * Run a command in a child process. * - * @param aCommandLine The process and any arguments to it all in a single - * string. + * @param aCommandLine The process and any arguments to it all in a single string. * @param aFlags The same args as allowed for wxExecute() * @param callback wxProcess implementing OnTerminate to be run when the child process finishes - * @return int - pid of process, 0 in case of error (like return values of - * wxExecute()) + * @return pid of process, 0 in case of error (like return values of wxExecute()). */ int ProcessExecute( const wxString& aCommandLine, int aFlags = wxEXEC_ASYNC, - wxProcess *callback = NULL ); + wxProcess *callback = nullptr ); /** * Return the help file's full path. @@ -99,13 +97,13 @@ wxString SearchHelpFileFullPath( const SEARCH_STACK& aSearchStack, const wxStrin */ bool EnsureFileDirectoryExists( wxFileName* aTargetFullFileName, const wxString& aBaseFilename, - REPORTER* aReporter = NULL ); + REPORTER* aReporter = nullptr ); /** * Replace any environment variable & text variable references with their values. * - * @param aString = a string containing (perhaps) references to env var - * @return a string where env var are replaced by their value + * @param aString a string containing (perhaps) references to env var + * @return the expanded environment variable. */ const wxString ExpandEnvVarSubstitutions( const wxString& aString, PROJECT* aProject ); @@ -128,19 +126,18 @@ const wxString ResolveUriByEnvVars( const wxString& aUri, PROJECT* aProject ); #ifdef __WXMAC__ /** * OSX specific function GetOSXKicadUserDataDir - * @return A wxString pointing to the user data directory for Kicad + * + * @return The macOS specific user data directory for KiCad. */ wxString GetOSXKicadUserDataDir(); /** - * OSX specific function GetOSXMachineDataDir - * @return A wxString pointing to the machine data directory for Kicad + * @return The macOS specific machine data directory for KiCad */ wxString GetOSXKicadMachineDataDir(); /** - * OSX specific function GetOSXKicadDataDir - * @return A wxString pointing to the bundle data directory for Kicad + * @return The macOS specific bundle data directory for KiCad */ wxString GetOSXKicadDataDir(); #endif @@ -180,16 +177,14 @@ namespace std /** * Helper function to print the given wxSize to a stream. * - * Used for debugging functions like EDA_ITEM::Show and also in unit - * testing fixtures. + * Used for debugging functions like EDA_ITEM::Show and also in unit testing fixtures. */ std::ostream& operator<<( std::ostream& out, const wxSize& size ); /** * Helper function to print the given wxPoint to a stream. * - * Used for debugging functions like EDA_ITEM::Show and also in unit - * testing fixtures. + * Used for debugging functions like EDA_ITEM::Show and also in unit testing fixtures. */ std::ostream& operator<<( std::ostream& out, const wxPoint& pt ); diff --git a/include/config_params.h b/include/config_params.h index 69178f5c3a..feedd4d1e6 100644 --- a/include/config_params.h +++ b/include/config_params.h @@ -37,18 +37,15 @@ using KIGFX::COLOR4D; -/* - * NOTE: Everything in this file is deprecated, it only remains because advanced_config depends on - * it for the moment. - */ - /** - * Function ConfigBaseWriteDouble - * This is a helper function to write doubles in config - * We cannot use wxConfigBase->Write for a double, because - * this function uses a format with very few digits in mantissa, - * and truncation issues are frequent. - * We use here a better floating format. + * A helper function to write doubles in configuration file. + * + * We cannot use wxConfigBase->Write for a double, because this function uses a format with + * very few digits in mantissa and truncation issues are frequent. We use here a better + * floating format. + * + * @note Everything in this file is deprecated, it only remains because advanced_config depends on + * it for the moment. */ void ConfigBaseWriteDouble( wxConfigBase* aConfig, const wxString& aKey, double aValue ); @@ -74,17 +71,34 @@ enum paramcfg_id { /** - * PARAM_CFG - * is a base class which establishes the interface functions ReadParam and SaveParam, + * A base class which establishes the interface functions ReadParam and SaveParam, * which are implemented by a number of derived classes, and these function's * doxygen comments are inherited also. - *

+ * * See kicad.odt or kicad.pdf, chapter 2 : * "Installation and configuration/Initialization of the default config". */ class PARAM_CFG { public: + PARAM_CFG( const wxString& ident, const paramcfg_id type, const wxChar* group = nullptr, + const wxString& legacy_ident = wxEmptyString ); + virtual ~PARAM_CFG() {} + + /** + * Read the value of the parameter stored in \a aConfig. + * + * @param aConfig the wxConfigBase that holds the parameter. + */ + virtual void ReadParam( wxConfigBase* aConfig ) const {}; + + /** + * Save the value of the parameter stored in \a aConfig. + * + * @param aConfig the wxConfigBase that can store the parameter. + */ + virtual void SaveParam( wxConfigBase* aConfig ) const {}; + wxString m_Ident; ///< Keyword in config data paramcfg_id m_Type; ///< Type of parameter wxString m_Group; ///< Group name (this is like a path in the config data) @@ -93,39 +107,14 @@ public: // If the m_Ident keyword isn't found, fall back and read values from m_Ident_legacy. // Note that values are always written to the current, non-legacy keyword. wxString m_Ident_legacy; - -public: - PARAM_CFG( const wxString& ident, const paramcfg_id type, const wxChar* group = NULL, - const wxString& legacy_ident = wxEmptyString ); - virtual ~PARAM_CFG() {} - - /** - * Function ReadParam - * reads the value of the parameter stored in aConfig - * @param aConfig = the wxConfigBase that holds the parameter - */ - virtual void ReadParam( wxConfigBase* aConfig ) const {}; - - /** - * Function SaveParam - * saves the value of the parameter stored in aConfig - * @param aConfig = the wxConfigBase that can store the parameter - */ - virtual void SaveParam( wxConfigBase* aConfig ) const {}; }; /** - * Configuration parameter - Integer Class - * + * Configuration object for integers. */ -class PARAM_CFG_INT : public PARAM_CFG +class PARAM_CFG_INT : public PARAM_CFG { -public: - int* m_Pt_param; ///< Pointer to the parameter value - int m_Min, m_Max; ///< Minimum and maximum values of the param type - int m_Default; ///< The default value of the parameter - public: PARAM_CFG_INT( const wxString& ident, int* ptparam, int default_val = 0, int min = std::numeric_limits::min(), @@ -140,147 +129,142 @@ public: virtual void ReadParam( wxConfigBase* aConfig ) const override; virtual void SaveParam( wxConfigBase* aConfig ) const override; + + int* m_Pt_param; ///< Pointer to the parameter value + int m_Min, m_Max; ///< Minimum and maximum values of the param type + int m_Default; ///< The default value of the parameter }; /** - * Configuration parameter - Integer Class - * with unit conversion. - * Mainly used to store an integer value in millimeters (or inches) - * and retrieve it in internal units - * the stored value is a floating number + * Configuration for integers with unit conversion. + * + * Mainly used to store an integer value in millimeters (or inches) and retrieve it in + * internal units. The stored value is a floating number. */ class PARAM_CFG_INT_WITH_SCALE : public PARAM_CFG_INT { -public: - double m_BIU_to_cfgunit; ///< the factor to convert the saved value in internal value - public: PARAM_CFG_INT_WITH_SCALE( const wxString& ident, int* ptparam, int default_val = 0, int min = std::numeric_limits::min(), int max = std::numeric_limits::max(), - const wxChar* group = NULL, double aBiu2cfgunit = 1.0, + const wxChar* group = nullptr, double aBiu2cfgunit = 1.0, const wxString& legacy_ident = wxEmptyString ); PARAM_CFG_INT_WITH_SCALE( bool insetup, const wxString& ident, int* ptparam, int default_val = 0, int min = std::numeric_limits::min(), int max = std::numeric_limits::max(), - const wxChar* group = NULL, double aBiu2cfgunit = 1.0, + const wxChar* group = nullptr, double aBiu2cfgunit = 1.0, const wxString& legacy_ident = wxEmptyString ); virtual void ReadParam( wxConfigBase* aConfig ) const override; virtual void SaveParam( wxConfigBase* aConfig ) const override; + +public: + double m_BIU_to_cfgunit; ///< the factor to convert the saved value in internal value }; /** - * Configuration parameter - Double Precision Class - * + * Configuration object for double precision floating point numbers. */ -class PARAM_CFG_DOUBLE : public PARAM_CFG +class PARAM_CFG_DOUBLE : public PARAM_CFG { public: + PARAM_CFG_DOUBLE( const wxString& ident, double* ptparam, + double default_val = 0.0, double min = 0.0, double max = 10000.0, + const wxChar* group = nullptr ); + PARAM_CFG_DOUBLE( bool Insetup, const wxString& ident, double* ptparam, + double default_val = 0.0, double min = 0.0, double max = 10000.0, + const wxChar* group = nullptr ); + + virtual void ReadParam( wxConfigBase* aConfig ) const override; + virtual void SaveParam( wxConfigBase* aConfig ) const override; + double* m_Pt_param; ///< Pointer to the parameter value double m_Default; ///< The default value of the parameter double m_Min, m_Max; ///< Minimum and maximum values of the param type - -public: - PARAM_CFG_DOUBLE( const wxString& ident, double* ptparam, - double default_val = 0.0, double min = 0.0, double max = 10000.0, - const wxChar* group = NULL ); - PARAM_CFG_DOUBLE( bool Insetup, const wxString& ident, double* ptparam, - double default_val = 0.0, double min = 0.0, double max = 10000.0, - const wxChar* group = NULL ); - - virtual void ReadParam( wxConfigBase* aConfig ) const override; - virtual void SaveParam( wxConfigBase* aConfig ) const override; }; /** - * Configuration parameter - Boolean Class - * + * Configuration object for booleans. */ -class PARAM_CFG_BOOL : public PARAM_CFG +class PARAM_CFG_BOOL : public PARAM_CFG { -public: - bool* m_Pt_param; ///< Pointer to the parameter value - int m_Default; ///< The default value of the parameter - public: PARAM_CFG_BOOL( const wxString& ident, bool* ptparam, - int default_val = false, const wxChar* group = NULL, + int default_val = false, const wxChar* group = nullptr, const wxString& legacy_ident = wxEmptyString ); PARAM_CFG_BOOL( bool Insetup, const wxString& ident, bool* ptparam, - int default_val = false, const wxChar* group = NULL, + int default_val = false, const wxChar* group = nullptr, const wxString& legacy_ident = wxEmptyString ); virtual void ReadParam( wxConfigBase* aConfig ) const override; virtual void SaveParam( wxConfigBase* aConfig ) const override; + + bool* m_Pt_param; ///< Pointer to the parameter value + int m_Default; ///< The default value of the parameter }; /** - * Configuration parameter - wxString Class - * + * Configuration object for wxString objects. */ class PARAM_CFG_WXSTRING : public PARAM_CFG { public: - wxString* m_Pt_param; ///< Pointer to the parameter value - wxString m_default; ///< The default value of the parameter - -public: - PARAM_CFG_WXSTRING( const wxString& ident, wxString* ptparam, const wxChar* group = NULL ); + PARAM_CFG_WXSTRING( const wxString& ident, wxString* ptparam, const wxChar* group = nullptr ); PARAM_CFG_WXSTRING( bool Insetup, const wxString& ident, wxString* ptparam, const wxString& default_val = wxEmptyString, - const wxChar* group = NULL ); + const wxChar* group = nullptr ); virtual void ReadParam( wxConfigBase* aConfig ) const override; virtual void SaveParam( wxConfigBase* aConfig ) const override; + + wxString* m_Pt_param; ///< Pointer to the parameter value + wxString m_default; ///< The default value of the parameter }; /** - * Configuration parameter - std::set + * Configuration object for a set of wxString objects. * */ class PARAM_CFG_WXSTRING_SET : public PARAM_CFG { public: - std::set* m_Pt_param; ///< Pointer to the parameter value - -public: - PARAM_CFG_WXSTRING_SET( const wxString& ident, std::set* ptparam, const wxChar* group = NULL ); + PARAM_CFG_WXSTRING_SET( const wxString& ident, std::set* ptparam, + const wxChar* group = nullptr ); PARAM_CFG_WXSTRING_SET( bool Insetup, const wxString& ident, std::set* ptparam, - const wxChar* group = NULL ); + const wxChar* group = nullptr ); virtual void ReadParam( wxConfigBase* aConfig ) const override; virtual void SaveParam( wxConfigBase* aConfig ) const override; + + std::set* m_Pt_param; ///< Pointer to the parameter value }; /** - * Configuration parameter - PARAM_CFG_FILENAME Class - * Same as PARAM_CFG_WXSTRING, but stores "\" as "/". - * and replace "/" by "\" under Windows. - * Used to store paths and filenames in config files + * Configuration object for a file name object. + * + * Same as #PARAM_CFG_WXSTRING but stores "\" as "/" and replace "/" by "\" under Windows. */ -class PARAM_CFG_FILENAME : public PARAM_CFG +class PARAM_CFG_FILENAME : public PARAM_CFG { -public: - wxString* m_Pt_param; ///< Pointer to the parameter value - public: PARAM_CFG_FILENAME( const wxString& ident, wxString* ptparam, - const wxChar* group = NULL ); + const wxChar* group = nullptr ); virtual void ReadParam( wxConfigBase* aConfig ) const override; virtual void SaveParam( wxConfigBase* aConfig ) const override; + + wxString* m_Pt_param; ///< Pointer to the parameter value }; @@ -290,9 +274,8 @@ public: wxArrayString* m_Pt_param; ///< Pointer to the parameter value public: - PARAM_CFG_LIBNAME_LIST( const wxChar* ident, - wxArrayString* ptparam, - const wxChar* group = NULL ); + PARAM_CFG_LIBNAME_LIST( const wxChar* ident, wxArrayString* ptparam, + const wxChar* group = nullptr ); virtual void ReadParam( wxConfigBase* aConfig ) const override; virtual void SaveParam( wxConfigBase* aConfig ) const override; @@ -300,22 +283,21 @@ public: /** - * Function wxConfigSaveSetups - * writes @a aList of PARAM_CFG to save configuration values to @a aCfg. + * Writes @a aList of #PARAM_CFG objects to @a aCfg. + * * Only elements with m_Setup set true will be saved, hence the function name. * - * @param aCfg where to save - * @param aList holds some configuration parameters, not all of which will - * necessarily be saved. + * @param aCfg where to save. + * @param aList holds some configuration parameters, not all of which will necessarily be saved. */ void wxConfigSaveSetups( wxConfigBase* aCfg, const std::vector& aList ); /** - * Function wxConfigSaveParams - * writes @a aList of PARAM_CFG to save configuration values to @a aCfg. + * Write @a aList of #PARAM_CFG objects @a aCfg. + * * Only elements with m_Setup set false will be saved, hence the function name. * - * @param aCfg where to save + * @param aCfg where to save. * @param aList holds some configuration parameters, not all of which will necessarily be saved. * @param aGroup indicates in which group the value should be saved, unless the PARAM_CFG provides * its own group, in which case it will take precedence. aGroup may be empty. @@ -324,8 +306,8 @@ void wxConfigSaveParams( wxConfigBase* aCfg, const std::vector& aLis const wxString& aGroup ); /** - * Function wxConfigLoadSetups - * uses @a aList of PARAM_CFG to load configuration values from @a aCfg. + * Use @a aList of #PARAM_CFG object to load configuration values from @a aCfg. + * * Only elements whose m_Setup field is true will be loaded. * * @param aCfg where to load from. @@ -334,8 +316,7 @@ void wxConfigSaveParams( wxConfigBase* aCfg, const std::vector& aLis void wxConfigLoadSetups( wxConfigBase* aCfg, const std::vector& aList ); /** - * Function wxConfigLoadParams - * uses @a aList of PARAM_CFG to load configuration values from @a aCfg. + * Use @a aList of #PARAM_CFG objects to load configuration values from @a aCfg. * Only elements whose m_Setup field is false will be loaded. * * @param aCfg where to load from. diff --git a/include/dialog_helpers.h b/include/dialog_helpers.h index a192cec39b..dbb1b4171e 100644 --- a/include/dialog_helpers.h +++ b/include/dialog_helpers.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2010 Jean-Pierre Charras, jaen-pierre.charras@gipsa-lab.inpg.com - * Copyright (C) 1992-2012 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -40,12 +40,10 @@ void ConvertMarkdown2Html( const wxString& aMarkdownInput, wxString& aHtmlOutput class EDA_DRAW_FRAME; /** - * EDA_LIST_DIALOG - * * A dialog which shows: - * a list of elements for selection, - * a text control to display help or info about the selected item. - * 2 buttons (OK and Cancel) + * - a list of elements for selection, + * - a text control to display help or info about the selected item. + * - 2 buttons (OK and Cancel) * */ class EDA_LIST_DIALOG : public EDA_LIST_DIALOG_BASE @@ -53,20 +51,17 @@ class EDA_LIST_DIALOG : public EDA_LIST_DIALOG_BASE public: /** - * Constructor: * @param aParent Pointer to the parent window. - * @param aTitle = The title shown on top. + * @param aTitle The title shown on top. * @param aItemHeaders an optional array containing the column header names for the dialog. - * @param aItemList = A wxArrayString of the list of elements. - * @param aRefText = An item name if an item must be preselected. + * @param aItemList A wxArrayString of the list of elements. + * @param aRefText An item name if an item must be preselected. */ EDA_LIST_DIALOG( EDA_DRAW_FRAME* aParent, const wxString& aTitle, const wxArrayString& aItemHeaders, const std::vector& aItemList, const wxString& aRefText ); - // ~EDA_LIST_DIALOG() {} - void SetListLabel( const wxString& aLabel ); void SetOKLabel( const wxString& aLabel ); @@ -74,11 +69,10 @@ public: void InsertItems( const std::vector& aItemList, int aPosition = 0 ); /** - * Function GetTextSelection - * return the selected text from \a aColumn in the wxListCtrl in the dialog. + * Return the selected text from \a aColumn in the wxListCtrl in the dialog. * * @param aColumn is the column to return the text from. - * @return a wxString object containing the selected text from \a aColumn. + * @return the selected text from \a aColumn. */ wxString GetTextSelection( int aColumn = 0 ); @@ -94,21 +88,11 @@ private: }; -/**************************************************************************/ -/* Class to edit/enter a coordinate (pair of values) ( INCHES or MM ) in */ -/* dialog boxes, */ -/**************************************************************************/ +/** + * Object to edit/enter a coordinate (pair of values) ( INCHES or MM ) in dialog boxes. + */ class EDA_POSITION_CTRL { -public: - EDA_UNITS m_UserUnit; - - wxTextCtrl* m_FramePosX; - wxTextCtrl* m_FramePosY; - -private: - wxStaticText* m_TextX, * m_TextY; - public: EDA_POSITION_CTRL( wxWindow* parent, const wxString& title, const wxPoint& pos_to_edit, EDA_UNITS user_unit, wxBoxSizer* BoxSizer ); @@ -118,13 +102,21 @@ public: void Enable( bool x_win_on, bool y_win_on ); void SetValue( int x_value, int y_value ); wxPoint GetValue() const; + + EDA_UNITS m_UserUnit; + + wxTextCtrl* m_FramePosX; + wxTextCtrl* m_FramePosY; + +private: + wxStaticText* m_TextX; + wxStaticText* m_TextY; }; -/************************************************************* - * Class to edit/enter a size (pair of values for X and Y size) - * ( INCHES or MM ) in dialog boxes - ***************************************************************/ +/** + * Object to edit/enter a size (pair of values for X and Y size ( INCHES or MM ) in dialog boxes. + */ class EDA_SIZE_CTRL : public EDA_POSITION_CTRL { public: @@ -132,9 +124,9 @@ public: EDA_UNITS user_unit, wxBoxSizer* BoxSizer ); ~EDA_SIZE_CTRL() { } + wxSize GetValue() const; }; - #endif // DIALOG_HELPERS_H_ diff --git a/include/dialog_shim.h b/include/dialog_shim.h index a08d72bd72..725ad33990 100644 --- a/include/dialog_shim.h +++ b/include/dialog_shim.h @@ -82,23 +82,7 @@ class WX_EVENT_LOOP; */ class DIALOG_SHIM : public wxDialog, public KIWAY_HOLDER { - /** - * Properly handle the wxCloseEvent when in the quasimodal mode when not calling - * EndQuasiModal which is possible with any dialog derived from #DIALOG_SHIM. - */ - void OnCloseWindow( wxCloseEvent& aEvent ); - - /** - * Properly handle the default button events when in the quasimodal mode when not - * calling EndQuasiModal which is possible with any dialog derived from #DIALOG_SHIM. - */ - void OnButton( wxCommandEvent& aEvent ); - -protected: - virtual void OnCharHook( wxKeyEvent& aEvt ); - public: - DIALOG_SHIM( wxWindow* aParent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, @@ -146,7 +130,6 @@ public: } protected: - /** * In all dialogs, we must call the same functions to fix minimal dlg size, the default * position and perhaps some others to fix a few issues depending on Windows Managers @@ -187,6 +170,27 @@ protected: */ void resetSize(); + virtual void OnCharHook( wxKeyEvent& aEvt ); + +private: + /** + * Properly handle the wxCloseEvent when in the quasimodal mode when not calling + * EndQuasiModal which is possible with any dialog derived from #DIALOG_SHIM. + */ + void OnCloseWindow( wxCloseEvent& aEvent ); + + /** + * Properly handle the default button events when in the quasimodal mode when not + * calling EndQuasiModal which is possible with any dialog derived from #DIALOG_SHIM. + */ + void OnButton( wxCommandEvent& aEvent ); + + void OnGridEditorShown( wxGridEvent& event ); + void OnGridEditorHidden( wxGridEvent& event ); + + DECLARE_EVENT_TABLE(); + +protected: EDA_UNITS m_units; // userUnits for display and parsing std::string m_hash_key; // alternate for class_map when classname re-used @@ -205,11 +209,6 @@ protected: std::vector m_tabOrder; -private: - void OnGridEditorShown( wxGridEvent& event ); - void OnGridEditorHidden( wxGridEvent& event ); - - DECLARE_EVENT_TABLE() }; #endif // DIALOG_SHIM_ diff --git a/include/dsnlexer.h b/include/dsnlexer.h index d16e2c92ae..a6c43a6283 100644 --- a/include/dsnlexer.h +++ b/include/dsnlexer.h @@ -2,7 +2,7 @@ * This program source code file is part of KICAD, a free EDA CAD application. * * Copyright (C) 2007-2010 SoftPLC Corporation, Dick Hollenbeck - * Copyright (C) 2007-2015 Kicad Developers, see change_log.txt for contributors. + * Copyright (C) 2007-2020 Kicad Developers, see change_log.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -34,8 +34,7 @@ #ifndef SWIG /** - * Struct KEYWORD - * holds a keyword string and its unique integer token. + * Hold a keyword string and its unique integer token. */ struct KEYWORD { @@ -51,9 +50,9 @@ struct KEYWORD /** - * Enum DSN_SYNTAX_T - * lists all the DSN lexer's tokens that are supported in lexing. It is up - * to the parser if it wants also to support them. + * List all the DSN lexer's tokens that are supported in lexing. + * + * It is up to the parser if it wants also to support them. */ enum DSN_SYNTAX_T { @@ -72,47 +71,384 @@ enum DSN_SYNTAX_T /** - * DSNLEXER - * implements a lexical analyzer for the SPECCTRA DSN file format. It - * reads lexical tokens from the current LINE_READER through the NextTok() - * function. + * Implement a lexical analyzer for the SPECCTRA DSN file format. + * + * It reads lexical tokens from the current #LINE_READER through the #NextTok() function. */ class DSNLEXER { +public: + + /** + * Initialize a DSN lexer and prepares to read from aFile which is already open and has + * \a aFilename. + * + * @param aKeywordTable is an array of KEYWORDS holding \a aKeywordCount. This + * token table need not contain the lexer separators such as '(' ')', etc. + * @param aKeywordCount is the count of tokens in aKeywordTable. + * @param aFile is an open file, which will be closed when this is destructed. + * @param aFileName is the name of the file + */ + DSNLEXER( const KEYWORD* aKeywordTable, unsigned aKeywordCount, + FILE* aFile, const wxString& aFileName ); + + /** + * Initialize a DSN lexer and prepares to read from @a aSExpression. + * + * @param aKeywordTable is an array of KEYWORDS holding \a aKeywordCount. This + * token table need not contain the lexer separators such as '(' ')', etc. + * @param aKeywordCount is the count of tokens in aKeywordTable. + * @param aSExpression is text to feed through a STRING_LINE_READER + * @param aSource is a description of aSExpression, used for error reporting. + */ + DSNLEXER( const KEYWORD* aKeywordTable, unsigned aKeywordCount, + const std::string& aSExpression, const wxString& aSource = wxEmptyString ); + + /** + * Initialize a DSN lexer and prepares to read from @a aSExpression. + * + * Use this one without a keyword table with the DOM parser in ptree.h. + * + * @param aSExpression is text to feed through a #STRING_LINE_READER + * @param aSource is a description of aSExpression, used for error reporting. + */ + DSNLEXER( const std::string& aSExpression, const wxString& aSource = wxEmptyString ); + + /** + * Initialize a DSN lexer and prepares to read from @a aLineReader which is already + * open, and may be in use by other DSNLEXERs also. + * + * No ownership is taken of @a aLineReader. This enables it to be used by other DSNLEXERs. + * + * @param aKeywordTable is an array of #KEYWORDS holding \a aKeywordCount. This + * token table need not contain the lexer separators such as '(' ')', etc. + * @param aKeywordCount is the count of tokens in aKeywordTable. + * @param aLineReader is any subclassed instance of LINE_READER, such as + * #STRING_LINE_READER or #FILE_LINE_READER. No ownership is taken. + */ + DSNLEXER( const KEYWORD* aKeywordTable, unsigned aKeywordCount, + LINE_READER* aLineReader = NULL ); + + virtual ~DSNLEXER(); + + /** + * Usable only for DSN lexers which share the same #LINE_READER. + * + * Synchronizes the pointers handling the data read by the #LINE_READER. Allows 2 + * #DNSLEXER objects to share the same current line, when switching from a #DNSLEXER + * to another #DNSLEXER + * @param aLexer the model. + * @return true if the sync can be made ( at least the same line reader ). + */ + bool SyncLineReaderWith( DSNLEXER& aLexer ); + + /** + * Change the behavior of this lexer into or out of "specctra mode". + * + * If specctra mode, then: + * -#) stringDelimiter can be changed. + * -#) KiCad quoting protocol is not in effect. + * -#) space_in_quoted_tokens is functional else none of the above are true. + * + * The default mode is non-specctra mode, meaning: + * -#) stringDelimiter cannot be changed. + * -#) KiCad quoting protocol is in effect. + * -#) space_in_quoted_tokens is not functional. + */ + void SetSpecctraMode( bool aMode ); + + /** + * Manage a stack of LINE_READERs in order to handle nested file inclusion. + * + * This function pushes aLineReader onto the top of a stack of LINE_READERs and makes + * it the current #LINE_READER with its own #GetSource(), line number and line text. + * A grammar must be designed such that the "include" token (whatever its various names), + * and any of its parameters are not followed by anything on that same line, + * because PopReader always starts reading from a new line upon returning to + * the original #LINE_READER. + */ + void PushReader( LINE_READER* aLineReader ); + + /** + * Delete the top most #LINE_READER from an internal stack of LINE_READERs and + * in the case of #FILE_LINE_READER this means the associated FILE is closed. + * + * The most recently used former #LINE_READER on the stack becomes the + * current #LINE_READER and its previous position in its input stream and the + * its latest line number should pertain. PopReader always starts reading + * from a new line upon returning to the previous #LINE_READER. A pop is only + * possible if there are at least 2 #LINE_READERs on the stack, since popping + * the last one is not supported. + * + * @return the LINE_READER that was in use before the pop, or NULL + * if there was not at least two readers on the stack and therefore the + * pop failed. + */ + LINE_READER* PopReader(); + + /** + * Return the next token found in the input file or DSN_EOF when reaching the end of + * file. + * + * Users should wrap this function to return an enum to aid in grammar debugging while + * running under a debugger, but leave this lower level function returning an int (so + * the enum does not collide with another usage). + * + * @return the type of token found next. + * @throw IO_ERROR only if the #LINE_READER throws it. + */ + int NextTok(); + + /** + * Call #NextTok() and then verifies that the token read in satisfies #IsSymbol(). + * + * @return the actual token read in. + * @throw IO_ERROR if the next token does not satisfy IsSymbol(). + */ + int NeedSYMBOL(); + + /** + * Call #NextTok() and then verifies that the token read in satisfies bool IsSymbol() or + * the next token is #DSN_NUMBER. + * + * @return the actual token read in. + * @throw IO_ERROR if the next token does not satisfy the above test. + */ + int NeedSYMBOLorNUMBER(); + + /** + * Call #NextTok() and then verifies that the token read is type #DSN_NUMBER. + * + * @return the actual token read in. + * @throw IO_ERROR if the next token does not satisfy the above test. + */ + int NeedNUMBER( const char* aExpectation ); + + /** + * Return whatever #NextTok() returned the last time it was called. + */ + int CurTok() const + { + return curTok; + } + + /** + * Return whatever NextTok() returned the 2nd to last time it was called. + */ + int PrevTok() const + { + return prevTok; + } + + /** + * Used to support "loose" matches (quoted tokens). + */ + int GetCurStrAsToken() const + { + return findToken( curText ); + } + + /** + * Change the string delimiter from the default " to some other character and return + * the old value. + * + * @param aStringDelimiter The character in lowest 8 bits. + * @return The old delimiter in the lowest 8 bits. + */ + char SetStringDelimiter( char aStringDelimiter ) + { + int old = stringDelimiter; + + if( specctraMode ) + stringDelimiter = aStringDelimiter; + + return old; + } + + /** + * Change the setting controlling whether a space in a quoted string isa terminator. + * + * @param val If true, means + */ + bool SetSpaceInQuotedTokens( bool val ) + { + bool old = space_in_quoted_tokens; + + if( specctraMode ) + space_in_quoted_tokens = val; + + return old; + } + + /** + * Change the handling of comments. + * + * If set true, comments are returned as single line strings with a terminating newline. + * Otherwise they are consumed by the lexer and not returned. + */ + bool SetCommentsAreTokens( bool val ) + { + bool old = commentsAreTokens; + commentsAreTokens = val; + return old; + } + + /** + * Check the next sequence of tokens and reads them into a wxArrayString if they are + * comments. + * + * Reading continues until a non-comment token is encountered, and such last read token + * remains as #CurTok() and as #CurText(). No push back or "un get" mechanism is used + * for this support. Upon return you simply avoid calling NextTok() for the next token, + * but rather #CurTok(). + * + * @return Heap allocated block of comments or NULL if none. The caller owns the + * allocation and must delete if not NULL. + */ + wxArrayString* ReadCommentLines(); + + /** + * Test a token to see if it is a symbol. + * + * This means it cannot be a special delimiter character such as #DSN_LEFT, #DSN_RIGHT, + * #DSN_QUOTE, etc. It may however, coincidentally match a keyword and still be a symbol. + */ + static bool IsSymbol( int aTok ); + + /** + * Throw an #IO_ERROR exception with an input file specific error message. + * + * @param aTok is the token/keyword type which was expected at the current input location. + * @throw IO_ERROR with the location within the input file of the problem. + */ + void Expecting( int aTok ) const; + + /** + * Throw an #IO_ERROR exception with an input file specific error message. + * + * @param aTokenList is the token/keyword type which was expected at the + * current input location, e.g. "pin|graphic|property". + * @throw IO_ERROR with the location within the input file of the problem. + */ + void Expecting( const char* aTokenList ) const; + + /** + * Throw an #IO_ERROR exception with an input file specific error message. + * + * @param aTok is the token/keyword type which was not expected at the + * current input location. + * @throw IO_ERROR with the location within the input file of the problem. + */ + void Unexpected( int aTok ) const; + + /** + * Throw an #IO_ERROR exception with an input file specific error message. + * + * @param aToken is the token which was not expected at the current input location. + * @throw IO_ERROR with the location within the input file of the problem. + */ + void Unexpected( const char* aToken ) const; + + /** + * Throw an #IO_ERROR exception with a message saying specifically that \a aTok + * is a duplicate of one already seen in current context. + * + * @param aTok is the token/keyword type which was not expected at the current input + * location. + * @throw IO_ERROR with the location within the input file of the problem. + */ + void Duplicate( int aTok ); + + /** + * Call #NextTok() and then verifies that the token read in is a #DSN_LEFT. + * + * @throw IO_ERROR if the next token is not a #DSN_LEFT + */ + void NeedLEFT(); + + /** + * Call #NextTok() and then verifies that the token read in is a #DSN_RIGHT. + * + * @throw IO_ERROR if the next token is not a #DSN_RIGHT + */ + void NeedRIGHT(); + + /** + * Return the C string representation of a #DSN_T value. + */ + const char* GetTokenText( int aTok ) const; + + /** + * Return a quote wrapped wxString representation of a token value. + */ + wxString GetTokenString( int aTok ) const; + + static const char* Syntax( int aTok ); + + /** + * Return a pointer to the current token's text. + */ + const char* CurText() const + { + return curText.c_str(); + } + + /** + * Return a reference to current token in std::string form. + */ + const std::string& CurStr() const + { + return curText; + } + + /** + * Return the current token text as a wxString, assuming that the input byte stream + * is UTF8 encoded. + */ + wxString FromUTF8() const + { + return wxString::FromUTF8( curText.c_str() ); + } + + /** + * Return the current line number within my #LINE_READER. + */ + int CurLineNumber() const + { + return reader->LineNumber(); + } + + /** + * Return the current line of text from which the #CurText() would return its token. + */ + const char* CurLine() const + { + return (const char*)(*reader); + } + + /** + * Return the current #LINE_READER source. + * + * @return source of the lines of text, e.g. a filename or "clipboard". + */ + const wxString& CurSource() const + { + return reader->GetSource(); + } + + /** + * Return the byte offset within the current line, using a 1 based index. + * + * @return a one based index into the current line. + */ + int CurOffset() const + { + return curOffset + 1; + } + #ifndef SWIG + protected: - bool iOwnReaders; ///< on readerStack, should I delete them? - const char* start; - const char* next; - const char* limit; - char dummy[1]; ///< when there is no reader. - - typedef std::vector READER_STACK; - - READER_STACK readerStack; ///< all the LINE_READERs by pointer. - LINE_READER* reader; ///< no ownership. ownership is via readerStack, maybe, if iOwnReaders - - bool specctraMode; ///< if true, then: - ///< 1) stringDelimiter can be changed - ///< 2) Kicad quoting protocol is not in effect - ///< 3) space_in_quoted_tokens is functional - ///< else not. - - char stringDelimiter; - bool space_in_quoted_tokens; ///< blank spaces within quoted strings - - bool commentsAreTokens; ///< true if should return comments as tokens - - int prevTok; ///< curTok from previous NextTok() call. - int curOffset; ///< offset within current line of the current token - - int curTok; ///< the current token obtained on last NextTok() - std::string curText; ///< the text of the current token - - const KEYWORD* keywords; ///< table sorted by CMake for bsearch() - unsigned keywordCount; ///< count of keywords table - KEYWORD_MAP keyword_hash; ///< fast, specialized "C string" hashtable - void init(); int readLine() @@ -136,12 +472,11 @@ protected: } /** - * Function findToken - * takes aToken string and looks up the string in the keywords table. + * Take @a aToken string and looks up the string in the keywords table. * * @param aToken is a string to lookup in the keywords table. - * @return int - with a value from the enum DSN_T matching the keyword text, - * or DSN_SYMBOL if @a aToken is not in the kewords table. + * @return with a value from the enum #DSN_T matching the keyword text, + * or #DSN_SYMBOL if @a aToken is not in the keywords table. */ int findToken( const std::string& aToken ) const; @@ -156,399 +491,40 @@ protected: return false; } + bool iOwnReaders; ///< on readerStack, should I delete them? + const char* start; + const char* next; + const char* limit; + char dummy[1]; ///< when there is no reader. + + typedef std::vector READER_STACK; + + READER_STACK readerStack; ///< all the LINE_READERs by pointer. + + ///< no ownership. ownership is via readerStack, maybe, if iOwnReaders + LINE_READER* reader; + + bool specctraMode; ///< if true, then: + ///< 1) stringDelimiter can be changed + ///< 2) Kicad quoting protocol is not in effect + ///< 3) space_in_quoted_tokens is functional + ///< else not. + + char stringDelimiter; + bool space_in_quoted_tokens; ///< blank spaces within quoted strings + + bool commentsAreTokens; ///< true if should return comments as tokens + + int prevTok; ///< curTok from previous NextTok() call. + int curOffset; ///< offset within current line of the current token + + int curTok; ///< the current token obtained on last NextTok() + std::string curText; ///< the text of the current token + + const KEYWORD* keywords; ///< table sorted by CMake for bsearch() + unsigned keywordCount; ///< count of keywords table + KEYWORD_MAP keyword_hash; ///< fast, specialized "C string" hashtable #endif // SWIG - -public: - - /** - * Constructor ( FILE*, const wxString& ) - * intializes a DSN lexer and prepares to read from aFile which - * is already open and has aFilename. - * - * @param aKeywordTable is an array of KEYWORDS holding \a aKeywordCount. This - * token table need not contain the lexer separators such as '(' ')', etc. - * @param aKeywordCount is the count of tokens in aKeywordTable. - * @param aFile is an open file, which will be closed when this is destructed. - * @param aFileName is the name of the file - */ - DSNLEXER( const KEYWORD* aKeywordTable, unsigned aKeywordCount, - FILE* aFile, const wxString& aFileName ); - - /** - * Constructor ( const KEYWORD*, unsigned, const std::string&, const wxString& ) - * intializes a DSN lexer and prepares to read from @a aSExpression. - * - * @param aKeywordTable is an array of KEYWORDS holding \a aKeywordCount. This - * token table need not contain the lexer separators such as '(' ')', etc. - * @param aKeywordCount is the count of tokens in aKeywordTable. - * @param aSExpression is text to feed through a STRING_LINE_READER - * @param aSource is a description of aSExpression, used for error reporting. - */ - DSNLEXER( const KEYWORD* aKeywordTable, unsigned aKeywordCount, - const std::string& aSExpression, const wxString& aSource = wxEmptyString ); - - /** - * Constructor ( const std::string&, const wxString& ) - * intializes a DSN lexer and prepares to read from @a aSExpression. Use this - * one without a keyword table with the DOM parser in ptree.h. - * - * @param aSExpression is text to feed through a STRING_LINE_READER - * @param aSource is a description of aSExpression, used for error reporting. - */ - DSNLEXER( const std::string& aSExpression, const wxString& aSource = wxEmptyString ); - - /** - * Constructor ( LINE_READER* ) - * intializes a DSN lexer and prepares to read from @a aLineReader which - * is already open, and may be in use by other DSNLEXERs also. No ownership - * is taken of @a aLineReader. This enables it to be used by other DSNLEXERs also. - * - * @param aKeywordTable is an array of KEYWORDS holding \a aKeywordCount. This - * token table need not contain the lexer separators such as '(' ')', etc. - * - * @param aKeywordCount is the count of tokens in aKeywordTable. - * - * @param aLineReader is any subclassed instance of LINE_READER, such as - * STRING_LINE_READER or FILE_LINE_READER. No ownership is taken. - */ - DSNLEXER( const KEYWORD* aKeywordTable, unsigned aKeywordCount, - LINE_READER* aLineReader = NULL ); - - virtual ~DSNLEXER(); - - /** - * Useable only for DSN lexers which share the same LINE_READER - * Synchronizes the pointers handling the data read by the LINE_READER - * Allows 2 DNSLEXER to share the same current line, when switching from a - * DNSLEXER to another DNSLEXER - * @param aLexer = the model - * @return true if the sync can be made ( at least the same line reader ) - */ - bool SyncLineReaderWith( DSNLEXER& aLexer ); - - /** - * Function SetSpecctraMode - * changes the behavior of this lexer into or out of "specctra mode". If - * specctra mode, then: - * 1) stringDelimiter can be changed - * 2) Kicad quoting protocol is not in effect - * 3) space_in_quoted_tokens is functional - * else none of the above are true. The default mode is non-specctra mode, meaning: - * 1) stringDelimiter cannot be changed - * 2) Kicad quoting protocol is in effect - * 3) space_in_quoted_tokens is not functional - */ - void SetSpecctraMode( bool aMode ); - - /** - * Function PushReader - * manages a stack of LINE_READERs in order to handle nested file inclusion. - * This function pushes aLineReader onto the top of a stack of LINE_READERs and makes - * it the current LINE_READER with its own GetSource(), line number and line text. - * A grammar must be designed such that the "include" token (whatever its various names), - * and any of its parameters are not followed by anything on that same line, - * because PopReader always starts reading from a new line upon returning to - * the original LINE_READER. - */ - void PushReader( LINE_READER* aLineReader ); - - /** - * Function PopReader - * deletes the top most LINE_READER from an internal stack of LINE_READERs and - * in the case of FILE_LINE_READER this means the associated FILE is closed. - * The most recently used former LINE_READER on the stack becomes the - * current LINE_READER and its previous position in its input stream and the - * its latest line number should pertain. PopReader always starts reading - * from a new line upon returning to the previous LINE_READER. A pop is only - * possible if there are at least 2 LINE_READERs on the stack, since popping - * the last one is not supported. - * - * @return LINE_READER* - is the one that was in use before the pop, or NULL - * if there was not at least two readers on the stack and therefore the - * pop failed. - */ - LINE_READER* PopReader(); - - // Some functions whose return value is best overloaded to return an enum - // in a derived class. - //----------------------------------- - - /** - * Function NextTok - * returns the next token found in the input file or DSN_EOF when reaching - * the end of file. Users should wrap this function to return an enum - * to aid in grammar debugging while running under a debugger, but leave - * this lower level function returning an int (so the enum does not collide - * with another usage). - * @return int - the type of token found next. - * @throw IO_ERROR - only if the LINE_READER throws it. - */ - int NextTok(); - - /** - * Function NeedSYMBOL - * calls NextTok() and then verifies that the token read in - * satisfies bool IsSymbol(). - * If not, an IO_ERROR is thrown. - * @return int - the actual token read in. - * @throw IO_ERROR, if the next token does not satisfy IsSymbol() - */ - int NeedSYMBOL(); - - /** - * Function NeedSYMBOLorNUMBER - * calls NextTok() and then verifies that the token read in - * satisfies bool IsSymbol() or tok==DSN_NUMBER. - * If not, an IO_ERROR is thrown. - * @return int - the actual token read in. - * @throw IO_ERROR, if the next token does not satisfy the above test - */ - int NeedSYMBOLorNUMBER(); - - /** - * Function NeedNUMBER - * calls NextTok() and then verifies that the token read is type DSN_NUMBER. - * If not, and IO_ERROR is thrown using text from aExpectation. - * @return int - the actual token read in. - * @throw IO_ERROR, if the next token does not satisfy the above test - */ - int NeedNUMBER( const char* aExpectation ); - - /** - * Function CurTok - * returns whatever NextTok() returned the last time it was called. - */ - int CurTok() const - { - return curTok; - } - - /** - * Function PrevTok - * returns whatever NextTok() returned the 2nd to last time it was called. - */ - int PrevTok() const - { - return prevTok; - } - - /** - * Function GetCurStrAsToken - * Used to support "loose" matches (quoted tokens) - */ - int GetCurStrAsToken() const - { - return findToken( curText ); - } - - //---------------------------------- - - - /** - * Function SetStringDelimiter - * changes the string delimiter from the default " to some other character - * and returns the old value. - * @param aStringDelimiter The character in lowest 8 bits. - * @return int - The old delimiter in the lowest 8 bits. - */ - char SetStringDelimiter( char aStringDelimiter ) - { - int old = stringDelimiter; - if( specctraMode ) - stringDelimiter = aStringDelimiter; - return old; - } - - /** - * Function SetSpaceInQuotedTokens - * changes the setting controlling whether a space in a quoted string is - * a terminator. - * @param val If true, means - */ - bool SetSpaceInQuotedTokens( bool val ) - { - bool old = space_in_quoted_tokens; - if( specctraMode ) - space_in_quoted_tokens = val; - return old; - } - - /** - * Function SetCommentsAreTokens - * changes the handling of comments. If set true, comments are returns - * as single line strings with a terminating newline, else they are - * consumed by the lexer and not returned. - */ - bool SetCommentsAreTokens( bool val ) - { - bool old = commentsAreTokens; - commentsAreTokens = val; - return old; - } - - /** - * Function ReadCommentLines - * checks the next sequence of tokens and reads them into a wxArrayString - * if they are comments. Reading continues until a non-comment token is - * encountered, and such last read token remains as CurTok() and as CurText(). - * No push back or "un get" mechanism is used for this support. Upon return - * you simply avoid calling NextTok() for the next token, but rather CurTok(). - * - * @return wxArrayString* - heap allocated block of comments, or NULL if none; - * caller owns the allocation and must delete if not NULL. - */ - wxArrayString* ReadCommentLines(); - - /** - * Function IsSymbol - * tests a token to see if it is a symbol. This means it cannot be a - * special delimiter character such as DSN_LEFT, DSN_RIGHT, DSN_QUOTE, etc. It may - * however, coincidentally match a keyword and still be a symbol. - */ - static bool IsSymbol( int aTok ); - - /** - * Function Expecting - * throws an IO_ERROR exception with an input file specific error message. - * @param aTok is the token/keyword type which was expected at the current input location. - * @throw IO_ERROR with the location within the input file of the problem. - */ - void Expecting( int aTok ) const; - - /** - * Function Expecting - * throws an IO_ERROR exception with an input file specific error message. - * @param aTokenList is the token/keyword type which was expected at the - * current input location, e.g. "pin|graphic|property" - * @throw IO_ERROR with the location within the input file of the problem. - */ - void Expecting( const char* aTokenList ) const; - - /** - * Function Unexpected - * throws an IO_ERROR exception with an input file specific error message. - * @param aTok is the token/keyword type which was not expected at the - * current input location. - * @throw IO_ERROR with the location within the input file of the problem. - */ - void Unexpected( int aTok ) const; - - /** - * Function Unexpected - * throws an IO_ERROR exception with an input file specific error message. - * @param aToken is the token which was not expected at the - * current input location. - * @throw IO_ERROR with the location within the input file of the problem. - */ - void Unexpected( const char* aToken ) const; - - /** - * Function Duplicate - * throws an IO_ERROR exception with a message saying specifically that aTok - * is a duplicate of one already seen in current context. - * @param aTok is the token/keyword type which was not expected at the - * current input location. - * @throw IO_ERROR with the location within the input file of the problem. - */ - void Duplicate( int aTok ); - - /** - * Function NeedLEFT - * calls NextTok() and then verifies that the token read in is a DSN_LEFT. - * If it is not, an IO_ERROR is thrown. - * @throw IO_ERROR, if the next token is not a DSN_LEFT - */ - void NeedLEFT(); - - /** - * Function NeedRIGHT - * calls NextTok() and then verifies that the token read in is a DSN_RIGHT. - * If it is not, an IO_ERROR is thrown. - * @throw IO_ERROR, if the next token is not a DSN_RIGHT - */ - void NeedRIGHT(); - - /** - * Function GetTokenText - * returns the C string representation of a DSN_T value. - */ - const char* GetTokenText( int aTok ) const; - - /** - * Function GetTokenString - * returns a quote wrapped wxString representation of a token value. - */ - wxString GetTokenString( int aTok ) const; - - static const char* Syntax( int aTok ); - - /** - * Function CurText - * returns a pointer to the current token's text. - */ - const char* CurText() const - { - return curText.c_str(); - } - - /** - * Function CurStr - * returns a reference to current token in std::string form. - */ - const std::string& CurStr() const - { - return curText; - } - - /** - * Function FromUTF8 - * returns the current token text as a wxString, assuming that the input - * byte stream is UTF8 encoded. - */ - wxString FromUTF8() const - { - return wxString::FromUTF8( curText.c_str() ); - } - - /** - * Function CurLineNumber - * returns the current line number within my LINE_READER - */ - int CurLineNumber() const - { - return reader->LineNumber(); - } - - /** - * Function CurLine - * returns the current line of text, from which the CurText() would return - * its token. - */ - const char* CurLine() const - { - return (const char*)(*reader); - } - - /** - * Function CurFilename - * returns the current LINE_READER source. - * @return const wxString& - the source of the lines of text, - * e.g. a filename or "clipboard". - */ - const wxString& CurSource() const - { - return reader->GetSource(); - } - - /** - * Function CurOffset - * returns the byte offset within the current line, using a 1 based index. - * @return int - a one based index into the current line. - */ - int CurOffset() const - { - return curOffset + 1; - } }; #endif // DSNLEXER_H_ diff --git a/include/eda_base_frame.h b/include/eda_base_frame.h index a9d8ba8a95..9440247236 100644 --- a/include/eda_base_frame.h +++ b/include/eda_base_frame.h @@ -3,7 +3,7 @@ * * Copyright (C) 2009-2015 Jean-Pierre Charras, jp.charras wanadoo.fr * Copyright (C) 2011 Wayne Stambaugh - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -96,140 +96,15 @@ wxDECLARE_EVENT( UNITS_CHANGED, wxCommandEvent ); * This class is not intended to be used directly. It provides support for automatic calls * to SaveSettings() function. SaveSettings() for a derived class can choose to do nothing, * or rely on basic SaveSettings() support in this base class to do most of the work by - * calling it from the derived class's SaveSettings(). - *

- * This class is not a KIWAY_PLAYER because KICAD_MANAGER_FRAME is derived from it - * and that class is not a player. - *

+ * calling it from the derived class's SaveSettings(). This class is not a #KIWAY_PLAYER + * because #KICAD_MANAGER_FRAME is derived from it and that class is not a player. */ class EDA_BASE_FRAME : public wxFrame, public TOOLS_HOLDER, public KIWAY_HOLDER { - /** - * (with its unexpected name so it does not collide with the real OnWindowClose() - * function provided in derived classes) is called just before a window - * closing, and is used to call a derivation specific - * SaveSettings(). SaveSettings() is called for all derived wxFrames in this - * base class overload. (Calling it from a destructor is deprecated since the - * wxFrame's position is not available in the destructor on linux.) In other words, - * you should not need to call SaveSettings() anywhere, except in this - * one function found only in this class. - */ - void windowClosing( wxCloseEvent& event ); - - wxWindow* findQuasiModalDialog(); - - /** - * Return true if the frame is shown in our modal mode - * and false if the frame is shown as an usual frame - * In modal mode, the caller that created the frame is responsible to Destroy() - * this frame after closing - */ - virtual bool IsModal() const { return false; } - -protected: - FRAME_T m_ident; // Id Type (pcb, schematic, library..) - wxPoint m_framePos; - wxSize m_frameSize; - bool m_maximizeByDefault; - - // These contain the frame size and position for when it is not maximized - wxPoint m_normalFramePos; - wxSize m_normalFrameSize; - - wxString m_aboutTitle; // Name of program displayed in About. - - wxAuiManager m_auimgr; - wxString m_perspective; // wxAuiManager perspective. - - WX_INFOBAR* m_infoBar; // Infobar for the frame - - wxString m_configName; // Prefix used to identify some params (frame size...) - // and to name some config files (legacy hotkey files) - - SETTINGS_MANAGER* m_settingsManager; - - FILE_HISTORY* m_fileHistory; // The frame's recently opened file list - - bool m_hasAutoSave; - bool m_autoSaveState; - int m_autoSaveInterval; // The auto save interval time in seconds. - wxTimer* m_autoSaveTimer; - - int m_undoRedoCountMax; // undo/Redo command Max depth - - UNDO_REDO_CONTAINER m_undoList; // Objects list for the undo command (old data) - UNDO_REDO_CONTAINER m_redoList; // Objects list for the redo command (old data) - - wxString m_mruPath; // Most recently used path. - - EDA_UNITS m_userUnits; - - // Map containing the UI update handlers registered with wx for each action - std::map m_uiUpdateMap; - bool m_isClosing; // Set by the close window event handler after frames are asked if they can close - // Allows other functions when called to know our state is cleanup - bool m_isNonUserClose; // Set by NonUserClose() to indicate that the user did not request the current close - - ///> Default style flags used for wxAUI toolbars - static constexpr int KICAD_AUI_TB_STYLE = wxAUI_TB_DEFAULT_STYLE | wxAUI_TB_PLAIN_BACKGROUND; - - /** - * @return the suffix to be appended to the file extension on backup - */ - static wxString GetBackupSuffix() - { - return wxT( "-bak" ); - } - - /** - * @return the string to prepend to a file name for automatic save. - */ - static wxString GetAutoSaveFilePrefix() - { - return wxT( "_autosave-" ); - } - - /** - * Handle the auto save timer event. - */ - void onAutoSaveTimer( wxTimerEvent& aEvent ); - - /** - * Return the auto save status of the application. - * - * Override this function if your derived frame supports automatic file saving. - */ - virtual bool isAutoSaveRequired() const { return false; } - - /** - * This should be overridden by the derived class to handle the auto save feature. - * - * @return true if the auto save was successful otherwise false. - */ - virtual bool doAutoSave(); - - virtual bool canCloseWindow( wxCloseEvent& aCloseEvent ) { return true; } - virtual void doCloseWindow() { } - - /** - * Called when when the units setting has changed to allow for any derived classes - * to handle refreshing and controls that have units based measurements in them. The - * default version only updates the status bar. Don't forget to call the default - * in your derived class or the status bar will not get updated properly. - */ - virtual void unitsChangeRefresh() { } - - /** - * Setup the UI conditions for the various actions and their controls in this frame. - */ - virtual void setupUIConditions(); - - DECLARE_EVENT_TABLE() - public: - EDA_BASE_FRAME( wxWindow* aParent, FRAME_T aFrameType, - const wxString& aTitle, const wxPoint& aPos, const wxSize& aSize, - long aStyle, const wxString& aFrameName, KIWAY* aKiway ); + EDA_BASE_FRAME( wxWindow* aParent, FRAME_T aFrameType, const wxString& aTitle, + const wxPoint& aPos, const wxSize& aSize, long aStyle, + const wxString& aFrameName, KIWAY* aKiway ); ~EDA_BASE_FRAME(); @@ -272,7 +147,7 @@ public: virtual void OnCharHook( wxKeyEvent& event ); /** - * The TOOL_DISPATCHER needs these to work around some issues in wxWidgets where the menu + * The #TOOL_DISPATCHER needs these to work around some issues in wxWidgets where the menu * events aren't captured by the menus themselves. */ void OnMenuEvent( wxMenuEvent& event ); @@ -293,12 +168,12 @@ public: virtual void UnregisterUIUpdateHandler( int aID ) override; /** - * Handles events generated when the UI is trying to figure out the current state of the UI controls - * related to TOOL_ACTIONS (e.g. enabled, checked, etc.). + * Handle events generated when the UI is trying to figure out the current state of the + * UI controls related to #TOOL_ACTIONS (e.g. enabled, checked, etc.). * * @param aEvent is the wxUpdateUIEvent to be processed. * @param aFrame is the frame to get the selection from - * @param aCond are the UI SELECTION_CONDITIONS used + * @param aCond are the #UI SELECTION_CONDITIONS used */ static void HandleUpdateUIEvent( wxUpdateUIEvent& aEvent, EDA_BASE_FRAME* aFrame, ACTION_CONDITIONS aCond ); @@ -317,7 +192,7 @@ public: bool IsType( FRAME_T aType ) const { return m_ident == aType; } /** - * Return a SEARCH_STACK pertaining to entire program. + * Return a #SEARCH_STACK pertaining to entire program. * * This is overloaded in #KICAD_MANAGER_FRAME */ @@ -331,104 +206,113 @@ public: void PrintMsg( const wxString& text ); /** - * @return the WX_INFOBAR that can be displayed on the top of the canvas + * @return the #WX_INFOBAR that can be displayed on the top of the canvas. */ WX_INFOBAR* GetInfoBar() { return m_infoBar; } /** - * Show the WX_INFOBAR displayed on the top of the canvas with a message - * and a Error icon on the left of the infobar. The infobar will be closed - * after a timeaout + * Show the #WX_INFOBAR displayed on the top of the canvas with a message + * and a error icon on the left of the infobar. + * + * The infobar will be closed after a timeout. + * * @param aErrorMsg is the message to display - * @param aShowCloseButton = true to show a close button on the right of the - * WX_INFOBAR + * @param aShowCloseButton true to show a close button on the right of the #WX_INFOBAR. */ void ShowInfoBarError( const wxString& aErrorMsg, bool aShowCloseButton = false ); /** - * Show the WX_INFOBAR displayed on the top of the canvas with a message - * and a Warning icon on the left of the infobar. The infobar will be closed - * after a timeaout - * @param aErrorMsg is the message to display - * @param aShowCloseButton = true to show a close button on the right of the - * WX_INFOBAR + * Show the #WX_INFOBAR displayed on the top of the canvas with a message and a warning + * icon on the left of the infobar. + * + * The infobar will be closed after a timeout. + * + * @param aErrorMsg is the message to display. + * @param aShowCloseButton true to show a close button on the right of the #WX_INFOBAR. */ void ShowInfoBarWarning( const wxString& aWarningMsg, bool aShowCloseButton = false ); /** - * Show the WX_INFOBAR displayed on the top of the canvas with a message - * and a Info icon on the left of the infobar. The infobar will be closed - * after a timeaout - * @param aErrorMsg is the message to display - * @param aShowCloseButton = true to show a close button on the right of the - * WX_INFOBAR + * Show the #WX_INFOBAR displayed on the top of the canvas with a message and an info + * icon on the left of the infobar. + * + * The infobar will be closed after a timeout. + * + * @param aErrorMsg is the message to display. + * @param aShowCloseButton true to show a close button on the right of the #WX_INFOBAR. */ void ShowInfoBarMsg( const wxString& aMsg, bool aShowCloseButton = false ); /** * Returns the settings object used in SaveSettings(), and is overloaded in - * KICAD_MANAGER_FRAME + * #KICAD_MANAGER_FRAME. */ virtual APP_SETTINGS_BASE* config() const; /** - * Function InstallPreferences * Allow a frame to load its preference panels (if any) into the preferences dialog. - * @param aParent a paged dialog into which the preference panels should be installed + * + * @param aParent a paged dialog into which the preference panels should be installed. */ virtual void InstallPreferences( PAGED_DIALOG* , PANEL_HOTKEYS_EDITOR* ) { } void LoadWindowState( const wxString& aFileName ); /** - * Loads window settings from the given settings object - * Normally called by LoadSettings unless the window in question is a child window that - * stores its settings somewhere other than APP_SETTINGS_BASE::m_Window + * Load window settings from the given settings object. + * + * Normally called by #LoadSettings() unless the window in question is a child window + * that* stores its settings somewhere other than #APP_SETTINGS_BASE::m_Window. */ void LoadWindowSettings( const WINDOW_SETTINGS* aCfg ); /** - * Saves window settings to the given settings object - * Normally called by SaveSettings unless the window in question is a child window that - * stores its settings somewhere other than APP_SETTINGS_BASE::m_Window + * Save window settings to the given settings object. + * + * Normally called by #SaveSettings unless the window in question is a child window that + * stores its settings somewhere other than #APP_SETTINGS_BASE::m_Window. */ void SaveWindowSettings( WINDOW_SETTINGS* aCfg ); /** * Load common frame parameters from a configuration file. * - * Don't forget to call the base method or your frames won't - * remember their positions and sizes. + * Don't forget to call the base method or your frames won't remember their positions + * and sizes. */ virtual void LoadSettings( APP_SETTINGS_BASE* aCfg ); /** - * Saves common frame parameters to a configuration data file. + * Save common frame parameters to a configuration data file. * - * Don't forget to call the base class's SaveSettings() from - * your derived SaveSettings() otherwise the frames won't remember their - * positions and sizes. + * Don't forget to call the base class's SaveSettings() from your derived + * #SaveSettings() otherwise the frames won't remember their positions and sizes. */ virtual void SaveSettings( APP_SETTINGS_BASE* aCfg ); /** - * Returns a pointer to the window settings for this frame. + * Return a pointer to the window settings for this frame. + * * By default, points to aCfg->m_Window for top-level frames. + * * @param aCfg is this frame's config object */ virtual WINDOW_SETTINGS* GetWindowSettings( APP_SETTINGS_BASE* aCfg ); /** - * Load frame state info from a configuration file - */ + * Load frame state info from a configuration file + */ virtual void LoadWindowState( const WINDOW_STATE& aState ); /** + * Get the configuration base name. + * + * This is usually the name of the frame set by CTOR, except for frames shown in + * multiple modes in which case the m_configName must be set to the base name so + * that a single configuration can be used. + * * @return a base name prefix used in Load/Save settings to build the full name of keys - * used in config. - * This is usually the name of the frame set by CTOR, except for frames shown in multiple - * modes in which case the m_configName must be set to the base name so that a single - * config can be used. + * used in configuration. */ wxString ConfigBaseName() override { @@ -440,19 +324,18 @@ public: * Save changes to the project settings to the project (.pro) file. * * The method is virtual so you can override it to call the suitable save method. - * The base method do nothing - * @param aAskForSave = true to open a dialog before saving the settings + * The base method does nothing. + * + * @param aAskForSave true to open a dialog before saving the settings. */ virtual void SaveProjectSettings() {}; - // Read/Save and Import/export hotkeys config - /** * Prompt the user for a hotkey file to read, and read it. * - * @param aActionMap = current hotkey map (over which the imported hotkeys will be applied) - * @param aDefaultShortname = a default short name (extension not needed) - * like eechema, kicad... + * @param aActionMap current hotkey map (over which the imported hotkeys will be applied). + * @param aDefaultShortname a default short name (extension not needed) like + * Eeschema, KiCad... */ void ImportHotkeyConfigFromFile( std::map aActionMap, const wxString& aDefaultShortname ); @@ -461,7 +344,7 @@ public: * Fetches the file name from the file history list. * * This removes the selected file, if this file does not exist. The menu is also updated, - * if FILE_HISTORY::UseMenu was called at init time + * if #FILE_HISTORY::UseMenu was called at initialization time. * * @param cmdId The command ID associated with the \a aFileHistory object. * @param type Please document me! @@ -486,8 +369,8 @@ public: * The menu is also updated, if FILE_HISTORY::UseMenu was called at init time. * * @param FullFileName The full file name including the path. - * @param aFileHistory The FILE_HISTORY in use. - * If NULL, the main application file history is used. + * @param aFileHistory The FILE_HISTORY in use. If NULL, the main application file + * history is used. */ void UpdateFileHistory( const wxString& FullFileName, FILE_HISTORY* aFileHistory = nullptr ); @@ -507,6 +390,7 @@ public: /** * Get the full filename + path of the currently opened file in the frame. + * * If no file is open, an empty string is returned. * * @return the filename and full path to the open file @@ -527,13 +411,13 @@ public: /** * Checks if \a aFileName can be written. - *

+ * * The function performs a number of tests on \a aFileName to verify that it can be saved. * If \a aFileName defines a path with no file name, them the path is tested for user write * permission. If \a aFileName defines a file name that does not exist in the path, the * path is tested for user write permission. If \a aFileName defines a file that already * exits, the file name is tested for user write permissions. - *

+ *> * @note The file name path must be set or an assertion will be raised on debug builds and * return false on release builds. * @param aFileName The full path and/or file name of the file to test. @@ -544,13 +428,13 @@ public: /** * Check if an auto save file exists for \a aFileName and takes the appropriate action * depending on the user input. - *

+ * * If an auto save file exists for \a aFileName, the user is prompted if they wish to * replace file \a aFileName with the auto saved file. If the user chooses to replace the * file, the backup file of \a aFileName is removed, \a aFileName is renamed to the backup * file name, and the auto save file is renamed to \a aFileName. If user chooses to keep * the existing version of \a aFileName, the auto save file is removed. - *

+ * * @param aFileName A wxFileName object containing the file name to check. */ void CheckForAutoSaveFile( const wxFileName& aFileName ); @@ -599,60 +483,50 @@ public: */ wxSize GetWindowSize(); - - /* general Undo/Redo command control */ - /** - * Function ClearUndoORRedoList (virtual). - * this function must remove the aItemCount old commands from aList - * and delete commands, pickers and picked items if needed - * Because picked items must be deleted only if they are not in use, this - * is a virtual pure function that must be created for SCH_SCREEN and - * PCB_SCREEN - * @param aList = the UNDO_REDO_CONTAINER of commands - * @param aItemCount = number of old commands to delete. -1 to remove all - * old commands this will empty the list of commands. - * Commands are deleted from the older to the last. + * Remove the \a aItemCount of old commands from \a aList and delete commands, pickers + * and picked items if needed. + * + * Because picked items must be deleted only if they are not in use, this is a virtual + * pure function that must be created for #SCH_SCREEN and #PCB_SCREEN. Commands are + * deleted from the older to the last. + * + * @param aList = the #UNDO_REDO_CONTAINER of commands. + * @param aItemCount number of old commands to delete. -1 to remove all old commands + * this will empty the list of commands. */ enum UNDO_REDO_LIST { UNDO_LIST, REDO_LIST }; virtual void ClearUndoORRedoList( UNDO_REDO_LIST aList, int aItemCount = -1 ) { } /** - * Function ClearUndoRedoList - * clear undo and redo list, using ClearUndoORRedoList() - * picked items are deleted by ClearUndoORRedoList() according to their - * status + * Clear the undo and redo list using #ClearUndoORRedoList() + * + * Picked items are deleted by ClearUndoORRedoList() according to their status. */ virtual void ClearUndoRedoList(); /** - * Function PushCommandToUndoList - * add a command to undo in undo list - * delete the very old commands when the max count of undo commands is - * reached - * ( using ClearUndoORRedoList) + * Add a command to undo in the undo list. + * + * Delete the very old commands when the max count of undo commands is reached. */ virtual void PushCommandToUndoList( PICKED_ITEMS_LIST* aItem ); /** - * Function PushCommandToRedoList - * add a command to redo in redo list - * delete the very old commands when the max count of redo commands is - * reached - * ( using ClearUndoORRedoList) + * Add a command to redo in the redo list. + * + * Delete the very old commands when the max count of redo commands is reached. */ virtual void PushCommandToRedoList( PICKED_ITEMS_LIST* aItem ); - /** PopCommandFromUndoList - * return the last command to undo and remove it from list - * nothing is deleted. + /** + * Return the last command to undo and remove it from list, nothing is deleted. */ virtual PICKED_ITEMS_LIST* PopCommandFromUndoList(); - /** PopCommandFromRedoList - * return the last command to undo and remove it from list - * nothing is deleted. + /** + * Return the last command to undo and remove it from list, nothing is deleted. */ virtual PICKED_ITEMS_LIST* PopCommandFromRedoList(); @@ -666,6 +540,137 @@ public: m_isNonUserClose = true; return Close( aForce ); } + +protected: + ///< Default style flags used for wxAUI toolbars. + static constexpr int KICAD_AUI_TB_STYLE = wxAUI_TB_DEFAULT_STYLE | wxAUI_TB_PLAIN_BACKGROUND; + + /** + * @return the suffix to be appended to the file extension on backup + */ + static wxString GetBackupSuffix() + { + return wxT( "-bak" ); + } + + /** + * @return the string to prepend to a file name for automatic save. + */ + static wxString GetAutoSaveFilePrefix() + { + return wxT( "_autosave-" ); + } + + /** + * Handle the auto save timer event. + */ + void onAutoSaveTimer( wxTimerEvent& aEvent ); + + /** + * Return the auto save status of the application. + * + * Override this function if your derived frame supports automatic file saving. + */ + virtual bool isAutoSaveRequired() const { return false; } + + /** + * This should be overridden by the derived class to handle the auto save feature. + * + * @return true if the auto save was successful otherwise false. + */ + virtual bool doAutoSave(); + + virtual bool canCloseWindow( wxCloseEvent& aCloseEvent ) { return true; } + virtual void doCloseWindow() { } + + /** + * Called when when the units setting has changed to allow for any derived classes + * to handle refreshing and controls that have units based measurements in them. + * + * The default version only updates the status bar. Don't forget to call the default + * in your derived class or the status bar will not get updated properly. + */ + virtual void unitsChangeRefresh() { } + + /** + * Setup the UI conditions for the various actions and their controls in this frame. + */ + virtual void setupUIConditions(); + + DECLARE_EVENT_TABLE() + +private: + /** + * (with its unexpected name so it does not collide with the real OnWindowClose() + * function provided in derived classes) is called just before a window + * closing, and is used to call a derivation specific SaveSettings(). + * + * #SaveSettings() is called for all derived wxFrames in this base class overload. + * Calling it from a destructor is deprecated since the wxFrame's position is not + * available in the destructor on linux. In other words, you should not need to + * call #SaveSettings() anywhere, except in this one function found only in this class. + */ + void windowClosing( wxCloseEvent& event ); + + wxWindow* findQuasiModalDialog(); + + /** + * Return true if the frame is shown in our modal mode and false if the frame is + * shown as an usual frame. + * + * In modal mode, the caller that created the frame is responsible to Destroy() + * this frame after closing. + */ + virtual bool IsModal() const { return false; } + +protected: + FRAME_T m_ident; // Id Type (pcb, schematic, library..) + wxPoint m_framePos; + wxSize m_frameSize; + bool m_maximizeByDefault; + + // These contain the frame size and position for when it is not maximized + wxPoint m_normalFramePos; + wxSize m_normalFrameSize; + + wxString m_aboutTitle; // Name of program displayed in About. + + wxAuiManager m_auimgr; + wxString m_perspective; // wxAuiManager perspective. + + WX_INFOBAR* m_infoBar; // Infobar for the frame + + wxString m_configName; // Prefix used to identify some params (frame size...) + // and to name some config files (legacy hotkey files) + + SETTINGS_MANAGER* m_settingsManager; + + FILE_HISTORY* m_fileHistory; // The frame's recently opened file list + + bool m_hasAutoSave; + bool m_autoSaveState; + int m_autoSaveInterval; // The auto save interval time in seconds. + wxTimer* m_autoSaveTimer; + + int m_undoRedoCountMax; // undo/Redo command Max depth + + UNDO_REDO_CONTAINER m_undoList; // Objects list for the undo command (old data) + UNDO_REDO_CONTAINER m_redoList; // Objects list for the redo command (old data) + + wxString m_mruPath; // Most recently used path. + + EDA_UNITS m_userUnits; + + ///< Map containing the UI update handlers registered with wx for each action. + std::map m_uiUpdateMap; + + ///< Set by the close window event handler after frames are asked if they can close. + ///< Allows other functions when called to know our state is cleanup. + bool m_isClosing; + + ///< Set by #NonUserClose() to indicate that the user did not request the current close. + bool m_isNonUserClose; + }; diff --git a/include/eda_doc.h b/include/eda_doc.h index 23d0826554..1bc2ce2af9 100644 --- a/include/eda_doc.h +++ b/include/eda_doc.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2009-2014 Jerry Jacobs - * Copyright (C) 1992-2019 KiCad Developers, see CHANGELOG.TXT for contributors. + * Copyright (C) 1992-2020 KiCad Developers, see CHANGELOG.TXT for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -33,24 +33,23 @@ /** - * Function KeywordMatch - * searches \a aKeyList for any words found in \a aDatabase. + * Search \a aKeyList for any words found in \a aDatabase. * * @return true if keyword is found. */ bool KeywordMatch( const wxString& aKeys, const wxString& aDatabase ); /** - * Function GetAssociatedDocument - * open a document (file) with the suitable browser. Environmental variables are - * substituted before the document name is resolved for either browser or file - * @param aParent = main frame - * @param aDocName = filename of file to open (Full filename or short filename) - * if \a aDocName begins with http: or ftp: or www. the default internet browser is launched + * Open a document (file) with the suitable browser. + * + * Environmental variables are substituted before the document name is resolved for + * either browser or file. If \a aDocName begins with http: or ftp: or www. the + * default internet browser is launched. + * + * @param aParent main frame. + * @param aDocName filename of file to open (Full filename or short filename). */ -bool GetAssociatedDocument( wxWindow* aParent, - const wxString& aDocName, - PROJECT* aProject ); +bool GetAssociatedDocument( wxWindow* aParent, const wxString& aDocName, PROJECT* aProject ); #endif /* __INCLUDE__EDA_DOC_H__ */ diff --git a/include/eda_draw_frame.h b/include/eda_draw_frame.h index b412fa9bfd..229acb2466 100644 --- a/include/eda_draw_frame.h +++ b/include/eda_draw_frame.h @@ -3,7 +3,7 @@ * * Copyright (C) 2009 Jean-Pierre Charras, jaen-pierre.charras@gipsa-lab.inpg.com * Copyright (C) 2011 Wayne Stambaugh - * Copyright (C) 1992-2019 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 1992-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -61,99 +61,26 @@ using KIGFX::RENDER_SETTINGS; /** - * The base class for create windows for drawing purpose. The Eeschema, Pcbnew and - * GerbView main windows are just a few examples of classes derived from EDA_DRAW_FRAME. + * The base class for create windows for drawing purpose. + * + * The Eeschema, Pcbnew and GerbView main windows are just a few examples of classes + * derived from EDA_DRAW_FRAME. */ class EDA_DRAW_FRAME : public KIWAY_PLAYER { - BASE_SCREEN* m_currentScreen; ///< current used SCREEN - EDA_DRAW_PANEL_GAL* m_canvas; - - ///< GAL display options - this is the frame's interface to setting GAL display options - KIGFX::GAL_DISPLAY_OPTIONS m_galDisplayOptions; - - /// Default display origin transforms object - ORIGIN_TRANSFORMS m_originTransforms; - -protected: - wxSocketServer* m_socketServer; - std::vector m_sockets; ///< interprocess communication - - std::unique_ptr m_file_checker; ///< prevents opening same file multiple times. - - bool m_showPageLimits; // True to display the page limits - COLOR4D m_gridColor; // Grid color - COLOR4D m_drawBgColor; // The background color of the draw canvas; BLACK for - // Pcbnew, BLACK or WHITE for eeschema - int m_undoRedoCountMax; // Default Undo/Redo command Max depth, to be handed - // to screens - bool m_polarCoords; // For those frames that support polar coordinates - - bool m_showBorderAndTitleBlock; // Show the worksheet (border and title block). - long m_firstRunDialogSetting; // Show first run dialog on startup - - wxChoice* m_gridSelectBox; - wxChoice* m_zoomSelectBox; - - ACTION_TOOLBAR* m_mainToolBar; - ACTION_TOOLBAR* m_auxiliaryToolBar; // Additional tools under main toolbar - ACTION_TOOLBAR* m_drawToolBar; // Drawing tools (typically on right edge of window) - ACTION_TOOLBAR* m_optionsToolBar; // Options (typically on left edge of window) - - wxFindReplaceData* m_findReplaceData; - wxArrayString m_findStringHistoryList; - wxArrayString m_replaceStringHistoryList; - - EDA_MSG_PANEL* m_messagePanel; - int m_msgFrameHeight; - - COLOR_SETTINGS* m_colorSettings; - - /// The current canvas type - EDA_DRAW_PANEL_GAL::GAL_TYPE m_canvasType; - - virtual void SetScreen( BASE_SCREEN* aScreen ) { m_currentScreen = aScreen; } - - void unitsChangeRefresh() override; - - void setupUnits( APP_SETTINGS_BASE* aCfg ); - - /** - * Determines the Canvas type to load (with prompt if required) and initializes m_canvasType - */ - void resolveCanvasType(); - - /** - * Returns the canvas type stored in the application settings. - */ - EDA_DRAW_PANEL_GAL::GAL_TYPE loadCanvasTypeSetting(); - - /** - * Stores the canvas type in the application settings. - */ - bool saveCanvasTypeSetting( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType ); - - /** - * Sets the common key-pair for exiting the application (Ctrl-Q) and ties it - * to the wxID_EXIT event id. This is useful in sub-applications to pass the event - * up to a non-owning window - */ - void initExitKey(); - public: - EDA_DRAW_FRAME( KIWAY* aKiway, wxWindow* aParent, - FRAME_T aFrameType, - const wxString& aTitle, - const wxPoint& aPos, const wxSize& aSize, - long aStyle, + EDA_DRAW_FRAME( KIWAY* aKiway, wxWindow* aParent, FRAME_T aFrameType, const wxString& aTitle, + const wxPoint& aPos, const wxSize& aSize, long aStyle, const wxString& aFrameName ); ~EDA_DRAW_FRAME(); /** - * Mark a schematic file as being in use. Use ReleaseFile() to undo this. + * Mark a schematic file as being in use. * - * @param aFileName = full path to the file. + * Use #ReleaseFile() to undo this. + * + * @param aFileName full path to the file. * @return false if the file was already locked, true otherwise. */ bool LockFile( const wxString& aFileName ); @@ -184,15 +111,17 @@ public: void ToggleUserUnits() override; /** - * Get the pair or units in current use. The primary unit is the main - * unit of the frame, and the secondary unit is the unit of the other - * system that was used most recently. + * Get the pair or units in current use. + * + * The primary unit is the main unit of the frame, and the secondary unit is the unit + * of the other system that was used most recently. */ void GetUnitPair( EDA_UNITS& aPrimaryUnit, EDA_UNITS& aSecondaryUnits ); /** - * Return the absolute coordinates of the origin of the snap grid. This is - * treated as a relative offset, and snapping will occur at multiples of the grid + * Return the absolute coordinates of the origin of the snap grid. + * + * This is treated as a relative offset and snapping will occur at multiples of the grid * size relative to this point. */ virtual const wxPoint& GetGridOrigin() const = 0; @@ -202,7 +131,7 @@ public: * Return the nearest \a aGridSize location to \a aPosition. * * @param aPosition The position to check. - * @return The nearst grid position. + * @return The nearest grid position. */ wxPoint GetNearestGridPosition( const wxPoint& aPosition ) const; @@ -236,23 +165,24 @@ public: * @param isDirectory indicates the library files are directories * @return true for OK; false for Cancel. */ - bool LibraryFileBrowser( bool doOpen, wxFileName& aFilename, - const wxString& wildcard, const wxString& ext, - bool isDirectory = false ); + bool LibraryFileBrowser( bool doOpen, wxFileName& aFilename, const wxString& wildcard, + const wxString& ext, bool isDirectory = false ); void CommonSettingsChanged( bool aEnvVarsChanged, bool aTextVarsChanged ) override; virtual wxString GetScreenDesc() const; /** - * Return a pointer to a BASE_SCREEN or one of its derivatives. It is overloaded by - * derived classes to return SCH_SCREEN or PCB_SCREEN. + * Return a pointer to a BASE_SCREEN or one of its derivatives. + * + * It is overloaded by derived classes to return #SCH_SCREEN or #PCB_SCREEN. */ virtual BASE_SCREEN* GetScreen() const { return m_currentScreen; } /** * Execute a remote command sent via socket (to port KICAD_PCB_PORT_SERVICE_NUMBER, * currently 4242). + * * Subclasses should override to implement actual command handlers. */ virtual void ExecuteRemoteCommand( const char* cmdline ){} @@ -267,6 +197,7 @@ public: /* * These 4 functions provide a basic way to show/hide grid and /get/set grid color. + * * These parameters are saved in KiCad config for each main frame. */ bool IsGridVisible() const; @@ -282,7 +213,7 @@ public: * application setting is saved. If you override this method, make sure you call down * to the base class. * - * @param event - Command event from the grid size combobox on the toolbar. + * @param event Command event from the grid size combobox on the toolbar. */ void OnSelectGrid( wxCommandEvent& event ); @@ -290,7 +221,7 @@ public: /** * Rebuild the grid combobox to respond to any changes in the GUI (units, user - * grid changes, etc.) + * grid changes, etc.). */ void UpdateGridSelectBox(); @@ -318,8 +249,8 @@ public: /** * Set the zoom factor when selected by the zoom list box in the main tool bar. * - * @note List position 0 is fit to page - * List position >= 1 = zoom (1 to zoom max) + * @note List position 0 is fit to page. + * List position >= 1 = zoom (1 to zoom max). * Last list position is custom zoom not in zoom list. */ virtual void OnSelectZoom( wxCommandEvent& event ); @@ -337,37 +268,37 @@ public: virtual void HardRedraw(); /** - * Redraw the screen with best zoom level and the best centering - * that shows all the page or the board + * Redraw the screen with best zoom level and the best centering that shows all the + * page or the board. */ virtual void Zoom_Automatique( bool aWarpPointer ); /** - * Useful to focus on a particular location, in find functions - * Move the graphic cursor (crosshair cursor) at a given coordinate and reframes - * the drawing if the requested point is out of view or if center on location is requested. + * Useful to focus on a particular location, in find functions. + * + * Move the graphic cursor (crosshair cursor) at a given coordinate and reframes the + * drawing if the requested point is out of view or if center on location is requested. + * * @param aPos is the point to go to. */ void FocusOnLocation( const wxPoint& aPos ); /** - * Function CreateBasicMenu - * - * Construct a "basic" menu for a tool, containing only items - * that apply to all tools (e.g. zoom and grid) + * Construct a "basic" menu for a tool, containing only items that apply to all tools + * (e.g. zoom and grid). */ void AddStandardSubMenus( TOOL_MENU& aMenu ); /** * Prints the page layout with the frame and the basic inscriptions. * - * @param aScreen screen to draw + * @param aScreen screen to draw. * @param aMils2Iu The mils to Iu conversion factor. * @param aFilename The filename to display in basic inscriptions. - * @param aSheetLayer The layer displayed from pcbnew. + * @param aSheetLayer The layer displayed from PcbNew. */ void PrintWorkSheet( RENDER_SETTINGS* aSettings, BASE_SCREEN* aScreen, double aMils2Iu, - const wxString &aFilename, const wxString &aSheetLayer = wxEmptyString ); + const wxString& aFilename, const wxString& aSheetLayer = wxEmptyString ); void DisplayToolMsg( const wxString& msg ) override; @@ -408,13 +339,12 @@ public: /** * Append a message to the message panel. * - * This helper method checks to make sure the message panel exists in - * the frame and appends a message to it using the message panel - * AppendMessage() method. + * This helper method checks to make sure the message panel exists in the frame and + * appends a message to it using the message panel AppendMessage() method. * - * @param aTextUpper - The message upper text. - * @param aTextLower - The message lower text. - * @param aPadding - Number of spaces to pad between messages. + * @param aTextUpper The message upper text. + * @param aTextLower The message lower text. + * @param aPadding Number of spaces to pad between messages. */ void AppendMsgPanel( const wxString& aTextUpper, const wxString& aTextLower, int aPadding = 6 ); @@ -434,9 +364,9 @@ public: /** * Helper function that erases the msg panel and then appends a single message * - * @param aTextUpper - The message upper text. - * @param aTextLower - The message lower text. - * @param aPadding - Number of spaces to pad between messages. + * @param aTextUpper The message upper text. + * @param aTextLower The message lower text. + * @param aPadding Number of spaces to pad between messages. */ void SetMsgPanel( const wxString& aTextUpper, const wxString& aTextLower, int aPadding = 6 ); @@ -453,7 +383,7 @@ public: /** * Print the page pointed by current screen, set by the calling print function. * - * @param aDC = wxDC given by the calling print function + * @param aDC wxDC given by the calling print function */ virtual void PrintPage( RENDER_SETTINGS* aSettings ); @@ -496,9 +426,9 @@ public: * false makes it ignore any items outside the PCB edge such as fabrication * notes. * - * @param aIncludeAllVisible - True = Include everything visible in bbox calculations - * False = Ignore some visible items (program dependent) - * @return BOX2I - Bounding box of document (ignoring some items as requested) + * @param aIncludeAllVisible True to include everything visible in bbox calculations, + * false to ignore some visible items (program dependent). + * @return Bounding box of the document (ignoring some items as requested). */ virtual const BOX2I GetDocumentExtents( bool aIncludeAllVisible = true ) const; @@ -508,6 +438,83 @@ public: void RecreateToolbars(); DECLARE_EVENT_TABLE() + +protected: + virtual void SetScreen( BASE_SCREEN* aScreen ) { m_currentScreen = aScreen; } + + void unitsChangeRefresh() override; + + void setupUnits( APP_SETTINGS_BASE* aCfg ); + + /** + * Determines the Canvas type to load (with prompt if required) and initializes m_canvasType + */ + void resolveCanvasType(); + + /** + * Returns the canvas type stored in the application settings. + */ + EDA_DRAW_PANEL_GAL::GAL_TYPE loadCanvasTypeSetting(); + + /** + * Stores the canvas type in the application settings. + */ + bool saveCanvasTypeSetting( EDA_DRAW_PANEL_GAL::GAL_TYPE aCanvasType ); + + /** + * Sets the common key-pair for exiting the application (Ctrl-Q) and ties it + * to the wxID_EXIT event id. + * + * This is useful in sub-applications to pass the event up to a non-owning window. + */ + void initExitKey(); + + wxSocketServer* m_socketServer; + std::vector m_sockets; ///< interprocess communication + + ///< Prevents opening same file multiple times. + std::unique_ptr m_file_checker; + + bool m_showPageLimits; // True to display the page limits + COLOR4D m_gridColor; // Grid color + COLOR4D m_drawBgColor; // The background color of the draw canvas; BLACK for + // Pcbnew, BLACK or WHITE for Eeschema + int m_undoRedoCountMax; // Default Undo/Redo command Max depth, to be handed + // to screens + bool m_polarCoords; // For those frames that support polar coordinates + + bool m_showBorderAndTitleBlock; // Show the worksheet (border and title block). + long m_firstRunDialogSetting; // Show first run dialog on startup + + wxChoice* m_gridSelectBox; + wxChoice* m_zoomSelectBox; + + ACTION_TOOLBAR* m_mainToolBar; + ACTION_TOOLBAR* m_auxiliaryToolBar; // Additional tools under main toolbar + ACTION_TOOLBAR* m_drawToolBar; // Drawing tools (typically on right edge of window) + ACTION_TOOLBAR* m_optionsToolBar; // Options (typically on left edge of window) + + wxFindReplaceData* m_findReplaceData; + wxArrayString m_findStringHistoryList; + wxArrayString m_replaceStringHistoryList; + + EDA_MSG_PANEL* m_messagePanel; + int m_msgFrameHeight; + + COLOR_SETTINGS* m_colorSettings; + + ///< The current canvas type. + EDA_DRAW_PANEL_GAL::GAL_TYPE m_canvasType; + +private: + BASE_SCREEN* m_currentScreen; ///< current used SCREEN + EDA_DRAW_PANEL_GAL* m_canvas; + + ///< This the frame's interface to setting GAL display options. + KIGFX::GAL_DISPLAY_OPTIONS m_galDisplayOptions; + + ///< Default display origin transforms object. + ORIGIN_TRANSFORMS m_originTransforms; }; #endif // DRAW_FRAME_H_ diff --git a/include/eda_item.h b/include/eda_item.h index 426aa2f355..f589b95de8 100644 --- a/include/eda_item.h +++ b/include/eda_item.h @@ -70,28 +70,28 @@ class MSG_PANEL_ITEM; /** - * Typedef INSPECTOR - * is used to inspect and possibly collect the - * (search) results of iterating over a list or tree of KICAD_T objects. - * Provide an implementation as needed to inspect EDA_ITEMs visited via - * EDA_ITEM::Visit() and EDA_ITEM::IterateForward(). - *

- * FYI the std::function may hold a lambda, std::bind, pointer to func, or - * ptr to member function, per modern C++. It is used primarily for searching, - * but not limited to that. It can also collect or modify the scanned objects. - * 'Capturing' lambdas are particularly convenient because they can use context - * and this often means @a aTestData is not used. + * Used to inspect and possibly collect the (search) results of iterating over a list or + * tree of #KICAD_T objects. * - * @param aItem An EDA_ITEM to examine. + * Provide an implementation as needed to inspect EDA_ITEMs visited via #EDA_ITEM::Visit() + * and #EDA_ITEM::IterateForward(). + * + * FYI the std::function may hold a lambda, std::bind, pointer to func, or ptr to member + * function, per modern C++. It is used primarily for searching, but not limited to that. + * It can also collect or modify the scanned objects. 'Capturing' lambdas are particularly + * convenient because they can use context and this often means @a aTestData is not used. + * + * @param aItem An #EDA_ITEM to examine. * @param aTestData is arbitrary data needed by the inspector to determine * if the EDA_ITEM under test meets its match criteria, and is often NULL * with the advent of capturing lambdas. * @return A #SEARCH_RESULT type #SEARCH_QUIT if the iterator function is to * stop the scan, else #SEARCH_CONTINUE; */ -typedef std::function< SEARCH_RESULT ( EDA_ITEM* aItem, void* aTestData ) > INSPECTOR_FUNC; +typedef std::function< SEARCH_RESULT ( EDA_ITEM* aItem, void* aTestData ) > INSPECTOR_FUNC; -typedef const INSPECTOR_FUNC& INSPECTOR; /// std::function passed to nested users by ref, avoids copying std::function +///< std::function passed to nested users by ref, avoids copying std::function. +typedef const INSPECTOR_FUNC& INSPECTOR; // These define are used for the .m_flags and .m_UndoRedoStatus member of the @@ -142,41 +142,20 @@ typedef const INSPECTOR_FUNC& INSPECTOR; /// std::function passed to nested u typedef unsigned STATUS_FLAGS; /** - * EDA_ITEM - * is a base class for most all the KiCad significant classes used in schematics and boards. + * A base class for most all the KiCad significant classes used in schematics and boards. */ class EDA_ITEM : public KIGFX::VIEW_ITEM { -public: - const KIID m_Uuid; - -private: - /** - * Run time identification, _keep private_ so it can never be changed after a ctor - * sets it. See comment near SetType() regarding virtual functions. - */ - KICAD_T m_structType; - -protected: - STATUS_FLAGS m_status; - EDA_ITEM* m_parent; ///< Linked list: Link (parent struct) - bool m_forceVisible; - STATUS_FLAGS m_flags; - -protected: - EDA_ITEM( EDA_ITEM* parent, KICAD_T idType ); - EDA_ITEM( KICAD_T idType ); - EDA_ITEM( const EDA_ITEM& base ); - public: virtual ~EDA_ITEM() { }; /** - * Function Type() + * Returns the type of object. * - * returns the type of object. This attribute should never be changed after a ctor sets - * it, so there is no public "setter" method. - * @return KICAD_T - the type of object. + * This attribute should never be changed after a ctor sets it, so there is no public + * "setter" method. + * + * @return the type of object. */ inline KICAD_T Type() const { return m_structType; } @@ -242,8 +221,8 @@ public: } /** - * Function IsType - * Checks whether the item is one of the listed types + * Check whether the item is one of the listed types. + * * @param aScanTypes List of item types * @return true if the item type is contained in the list aScanTypes */ @@ -262,9 +241,8 @@ public: } /** - * Function SetForceVisible - * is used to set and cleag force visible flag used to force the item to be drawn - * even if it's draw attribute is set to not visible. + * Set and clear force visible flag used to force the item to be drawn even if it's draw + * attribute is set to not visible. * * @param aEnable True forces the item to be drawn. False uses the item's visibility * setting to determine if the item is to be drawn. @@ -274,8 +252,7 @@ public: bool IsForceVisible() const { return m_forceVisible; } /** - * Function GetMsgPanelInfo - * populates \a aList of #MSG_PANEL_ITEM objects with it's internal state for display + * Populate \a aList of #MSG_PANEL_ITEM objects with it's internal state for display * purposes. * * @param aList is the list to populate. @@ -285,8 +262,7 @@ public: } /** - * Function HitTest - * tests if \a aPosition is contained within or on the bounding box of an item. + * Test if \a aPosition is contained within or on the bounding box of an item. * * @param aPosition A reference to a wxPoint object containing the coordinates to test. * @param aAccuracy Increase the item bounding box by this amount. @@ -298,10 +274,9 @@ public: } /** - * Function HitTest - * tests if \a aRect intersects or is contained within the bounding box of an item. + * Test if \a aRect intersects or is contained within the bounding box of an item. * - * @param aRect A reference to a EDA_RECT object containing the rectangle to test. + * @param aRect A reference to a #EDA_RECT object containing the rectangle to test. * @param aContained Set to true to test for containment instead of an intersection. * @param aAccuracy Increase \a aRect by this amount. * @return True if \a aRect contains or intersects the item bounding box. @@ -312,13 +287,11 @@ public: } /** - * Function GetBoundingBox - * returns the orthogonal, bounding box of this object for display - * purposes. + * Return the orthogonal bounding box of this object for display purposes. + * * This box should be an enclosing perimeter for visible components of this * object, and the units should be in the pcb or schematic coordinate - * system. - * It is OK to overestimate the size by a few counts. + * system. It is OK to overestimate the size by a few counts. */ virtual const EDA_RECT GetBoundingBox() const; @@ -326,15 +299,13 @@ public: virtual void SetPosition( const wxPoint& aPos ) {}; /** - * Function GetFocusPosition - * similar to GetPosition, but allows items to return their visual center rather + * Similar to GetPosition, but allows items to return their visual center rather * than their anchor. */ virtual const wxPoint GetFocusPosition() const { return GetPosition(); } /** - * Function Clone - * creates a duplicate of this item with linked list members set to NULL. + * Create a duplicate of this item with linked list members set to NULL. * * The default version will return NULL in release builds and likely crash the * program. In debug builds, a warning message indicating the derived class @@ -348,25 +319,23 @@ public: virtual EDA_ITEM* Clone() const; // should not be inline, to save the ~ 6 bytes per call site. /** - * Function Visit - * may be re-implemented for each derived class in order to handle - * all the types given by its member data. Implementations should call - * inspector->Inspect() on types in scanTypes[], and may use - * IterateForward() - * to do so on lists of such data. - * @param inspector An INSPECTOR instance to use in the inspection. + * May be re-implemented for each derived class in order to handle all the types given + * by its member data. + * + * Implementations should call inspector->Inspect() on types in scanTypes[], and may use + * #IterateForward() to do so on lists of such data. + * + * @param inspector An #INSPECTOR instance to use in the inspection. * @param testData Arbitrary data used by the inspector. - * @param scanTypes Which KICAD_T types are of interest and the order + * @param scanTypes Which# KICAD_T types are of interest and the order * is significant too, terminated by EOT. - * @return SEARCH_RESULT SEARCH_QUIT if the Iterator is to stop the scan, - * else SCAN_CONTINUE, and determined by the inspector. + * @return #SEARCH_RESULT SEARCH_QUIT if the Iterator is to stop the scan, + * else #SCAN_CONTINUE, and determined by the inspector. */ virtual SEARCH_RESULT Visit( INSPECTOR inspector, void* testData, const KICAD_T scanTypes[] ); /** - * @copydoc SEARCH_RESULT IterateForward( EDA_ITEM*, INSPECTOR, void*, const KICAD_T ) - * - * This changes first parameter to avoid the DList and use the main queue instead + * This changes first parameter to avoid the DList and use the main queue instead. */ template< class T > static SEARCH_RESULT IterateForward( std::deque& aList, @@ -385,9 +354,7 @@ public: } /** - * @copydoc SEARCH_RESULT IterateForward( EDA_ITEM*, INSPECTOR, void*, const KICAD_T ) - * - * This changes first parameter to avoid the DList and use std::vector instead + * Change first parameter to avoid the DList and use std::vector instead. */ template static SEARCH_RESULT IterateForward( @@ -404,43 +371,41 @@ public: } /** - * Function GetClass - * returns the class name. - * @return wxString + * Return the class name. */ virtual wxString GetClass() const = 0; /** - * Function GetSelectMenuText - * returns the text to display to be used in the selection clarification context menu - * when multiple items are found at the current cursor position. The default version - * of this function raises an assertion in the debug mode and returns a string to - * indicate that it was not overridden to provide the object specific text. + * Return the text to display to be used in the selection clarification context menu + * when multiple items are found at the current cursor position. + * + * The default version of this function raises an assertion in the debug mode and + * returns a string to indicate that it was not overridden to provide the object + * specific text. * * @return The menu text string. */ virtual wxString GetSelectMenuText( EDA_UNITS aUnits ) const; /** - * Function GetMenuImage - * returns a pointer to an image to be used in menus. The default version returns - * the right arrow image. Override this function to provide object specific menu - * images. + * Return a pointer to an image to be used in menus. + * + * The default version returns the right arrow image. Override this function to provide + * object specific menu images. + * * @return The menu image associated with the item. */ virtual BITMAP_DEF GetMenuImage() const; /** - * Function Matches - * compares the item against the search criteria in \a aSearchData. + * Compare the item against the search criteria in \a aSearchData. * * The base class returns false since many of the objects derived from EDA_ITEM * do not have any text to search. * * @param aSearchData A reference to a wxFindReplaceData object containing the * search criteria. - * @param aAuxData A pointer to optional data required for the search or NULL - * if not used. + * @param aAuxData A pointer to optional data required for the search or NULL if not used. * @return True if the item's text matches the search criteria in \a aSearchData. */ virtual bool Matches( wxFindReplaceData& aSearchData, void* aAuxData ) @@ -449,40 +414,34 @@ public: } /** - * Helper function used in search and replace dialog - * Function Replace - * performs a text replace on \a aText using the find and replace criteria in + * Perform a text replace on \a aText using the find and replace criteria in * \a aSearchData on items that support text find and replace. * * @param aSearchData A reference to a wxFindReplaceData object containing the * search and replace criteria. - * @param aText A reference to a wxString object containing the text to be - * replaced. + * @param aText A reference to a wxString object containing the text to be replaced. * @return True if \a aText was modified, otherwise false. */ static bool Replace( wxFindReplaceData& aSearchData, wxString& aText ); /** - * Function Replace - * performs a text replace using the find and replace criteria in \a aSearchData + * Perform a text replace using the find and replace criteria in \a aSearchData * on items that support text find and replace. * * This function must be overridden for items that support text replace. * - * @param aSearchData A reference to a wxFindReplaceData object containing the - * search and replace criteria. - * @param aAuxData A pointer to optional data required for the search or NULL - * if not used. + * @param aSearchData A reference to a wxFindReplaceData object containing the search and + * replace criteria. + * @param aAuxData A pointer to optional data required for the search or NULL if not used. * @return True if the item text was modified, otherwise false. */ - virtual bool Replace( wxFindReplaceData& aSearchData, void* aAuxData = NULL ) { return false; } + virtual bool Replace( wxFindReplaceData& aSearchData, void* aAuxData = nullptr ) + { + return false; + } /** - * Function IsReplaceable - *

- * Override this method in any derived object that supports test find and - * replace. - *

+ * Override this method in any derived object that supports test find and replace. * * @return True if the item has replaceable text that can be modified using * the find and replace dialog. @@ -498,9 +457,8 @@ public: bool operator<( const EDA_ITEM& aItem ) const; /** - * Function Sort - * is a helper function to be used by the C++ STL sort algorithm for sorting a STL - * container of EDA_ITEM pointers. + * Helper function to be used by the C++ STL sort algorithm for sorting a STL + * container of #EDA_ITEM pointers. * * @param aLeft The left hand item to compare. * @param aRight The right hand item to compare. @@ -509,8 +467,7 @@ public: static bool Sort( const EDA_ITEM* aLeft, const EDA_ITEM* aRight ) { return *aLeft < *aRight; } /** - * Operator assignment - * is used to assign the members of \a aItem to another object. + * Assign the members of \a aItem to another object. */ EDA_ITEM& operator=( const EDA_ITEM& aItem ); @@ -521,32 +478,37 @@ public: #if defined(DEBUG) /** - * Function Show - * is used to output the object tree, currently for debugging only. + * Output the object tree, currently for debugging only. + * + * This is pure virtual so compiler warns if somebody mucks up a derived declaration. + * * @param nestLevel An aid to prettier tree indenting, and is the level * of nesting of this object within the overall tree. * @param os The ostream& to output to. */ virtual void Show( int nestLevel, std::ostream& os ) const = 0; - // pure virtual so compiler warns if somebody mucks up a derived declaration void ShowDummy( std::ostream& os ) const; ///< call this if you are a lazy developer /** - * Function NestedSpace - * outputs nested space for pretty indenting. - * @param nestLevel The nest count + * Output nested space for pretty indenting. + * + * @param nestLevel The nest count. * @param os The ostream&, where to output - * @return std::ostream& - for continuation. + * @return The std::ostream& for continuation. **/ static std::ostream& NestedSpace( int nestLevel, std::ostream& os ); #endif protected: + EDA_ITEM( EDA_ITEM* parent, KICAD_T idType ); + EDA_ITEM( KICAD_T idType ); + EDA_ITEM( const EDA_ITEM& base ); + /** - * Function Matches - * compares \a aText against search criteria in \a aSearchData. + * Compare \a aText against search criteria in \a aSearchData. + * * This is a helper function for simplify derived class logic. * * @param aText A reference to a wxString object containing the string to test. @@ -554,12 +516,27 @@ protected: * @return True if \a aText matches the search criteria in \a aSearchData. */ bool Matches( const wxString& aText, wxFindReplaceData& aSearchData ); + +public: + const KIID m_Uuid; + +protected: + STATUS_FLAGS m_status; + EDA_ITEM* m_parent; ///< Linked list: Link (parent struct) + bool m_forceVisible; + STATUS_FLAGS m_flags; + +private: + /** + * Run time identification, _keep private_ so it can never be changed after a ctor + * sets it. See comment near SetType() regarding virtual functions. + */ + KICAD_T m_structType; }; /** - * Function new_clone - * provides cloning capabilities for all Boost pointer containers of EDA_ITEM pointers. + * Provide cloning capabilities for all Boost pointer containers of #EDA_ITEM pointers. * * @param aItem EDA_ITEM to clone. * @return Clone of \a aItem. @@ -575,4 +552,4 @@ inline EDA_ITEM* new_clone( const EDA_ITEM& aItem ) { return aItem.Clone(); } */ typedef std::vector< EDA_ITEM* > EDA_ITEMS; -#endif // EDA_ITEM_H \ No newline at end of file +#endif // EDA_ITEM_H diff --git a/include/eda_rect.h b/include/eda_rect.h index 3ec9e1c35d..1e64a54857 100644 --- a/include/eda_rect.h +++ b/include/eda_rect.h @@ -2,8 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2018 Jean-Pierre Charras, jp.charras at wanadoo.fr - * Copyright (C) 2004-2014 KiCad Developers, see change_log.txt for contributors. - * Copyright (C) 2018 KiCad Developers, see AUTHORS.txt for contributors. + * Copyright (C) 2004-2020 KiCad Developers, see AUTHORS.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -34,12 +33,11 @@ #include /** - * EDA_RECT - * handles the component boundary box. - * This class is similar to wxRect, but some wxRect functions are very curious, - * and are working only if dimensions are >= 0 (not always the case in KiCad) - * and also KiCad needs some specific method. - * so I prefer this more suitable class + * Handle the component boundary box. + * + * This class is similar to wxRect, but some wxRect functions are very curious, and are + * working only if dimensions are >= 0 (not always the case in KiCad) and also KiCad needs + * some specific method which makes this a more suitable class. */ class EDA_RECT { @@ -61,50 +59,44 @@ public: wxPoint Centre() const { - return wxPoint( m_pos.x + ( m_size.x >> 1 ), - m_pos.y + ( m_size.y >> 1 ) ); + return wxPoint( m_pos.x + ( m_size.x >> 1 ), m_pos.y + ( m_size.y >> 1 ) ); } /** - * Function Move - * moves the rectangle by the \a aMoveVector. - * @param aMoveVector A wxPoint that is the value to move this rectangle + * Move the rectangle by the \a aMoveVector. + * + * @param aMoveVector A wxPoint that is the value to move this rectangle. */ void Move( const wxPoint& aMoveVector ); /** - * Function Normalize - * ensures that the height ant width are positive. + * Ensures that the height ant width are positive. */ void Normalize(); /** - * Function Contains - * @param aPoint = the wxPoint to test - * @return true if aPoint is inside the boundary box. A point on a edge is seen as inside + * @param aPoint the wxPoint to test. + * @return true if aPoint is inside the boundary box. A point on a edge is seen as inside. */ bool Contains( const wxPoint& aPoint ) const; /** - * Function Contains - * @param x = the x coordinate of the point to test - * @param y = the x coordinate of the point to test + * @param x the x coordinate of the point to test. + * @param y the x coordinate of the point to test. * @return true if point is inside the boundary box. A point on a edge is seen as inside */ bool Contains( int x, int y ) const { return Contains( wxPoint( x, y ) ); } /** - * Function Contains - * @param aRect = the EDA_RECT to test - * @return true if aRect is Contained. A common edge is seen as contained + * @param aRect the EDA_RECT to test. + * @return true if aRect is Contained. A common edge is seen as contained. */ bool Contains( const EDA_RECT& aRect ) const; const wxSize GetSize() const { return m_size; } /** - * @brief GetSizeMax - * @return the max size dimension + * @return the max size dimension. */ int GetSizeMax() const { return ( m_size.x > m_size.y ) ? m_size.x : m_size.y; } @@ -114,7 +106,10 @@ public: const wxPoint GetOrigin() const { return m_pos; } const wxPoint GetPosition() const { return m_pos; } const wxPoint GetEnd() const { return wxPoint( m_pos.x + m_size.x, m_pos.y + m_size.y ); } - const wxPoint GetCenter() const { return wxPoint( m_pos.x + ( m_size.x / 2 ), m_pos.y + ( m_size.y / 2 ) ); } + const wxPoint GetCenter() const + { + return wxPoint( m_pos.x + ( m_size.x / 2 ), m_pos.y + ( m_size.y / 2 ) ); + } int GetWidth() const { return m_size.x; } int GetHeight() const { return m_size.y; } @@ -203,8 +198,7 @@ public: } /** - * Function RevertYAxis - * Mirror the rectangle from the X axis (negate Y pos and size) + * Mirror the rectangle from the X axis (negate Y pos and size). */ void RevertYAxis() { @@ -214,42 +208,40 @@ public: } /** - * Function Intersects - * tests for a common area between rectangles. + * Test for a common area between rectangles. * * @param aRect A rectangle to test intersection with. - * @return bool - true if the argument rectangle intersects this rectangle. + * @return true if the argument rectangle intersects this rectangle. * (i.e. if the 2 rectangles have at least a common point) */ bool Intersects( const EDA_RECT& aRect ) const; /** - * Tests for a common area between this rectangle, - * and a rectangle with arbitrary rotation + * Tests for a common area between this rectangle, and a rectangle with arbitrary rotation * - * @param aRect a rectangle to test intersection with - * @param aRot rectangle rotation (in 1/10 degrees) + * @param aRect a rectangle to test intersection with. + * @param aRot rectangle rotation (in 1/10 degrees). */ bool Intersects( const EDA_RECT& aRect, double aRot ) const; /** - * Function Intersects - * tests for a common area between a segment and this rectangle. + * Test for a common area between a segment and this rectangle. * * @param aPoint1 First point of the segment to test intersection with. * @param aPoint2 Second point of the segment to test intersection with. - * @return bool - true if the argument segment intersects this rectangle. + * @return true if the argument segment intersects this rectangle. * (i.e. if the segment and rectangle have at least a common point) */ bool Intersects( const wxPoint& aPoint1, const wxPoint& aPoint2 ) const; /** - * Tests for intersection between a segment and this rectangle, returning the intersections - * @param aPoint1 is the first point of the segment to test intersection with - * @param aPoint2 is the second point of the segment to test intersection with - * @param aIntersection1 will be filled with the first intersection point, if any - * @param aIntersection2 will be filled with the second intersection point, if any - * @return true if the segment intersects the rect + * Test for intersection between a segment and this rectangle, returning the intersections. + * + * @param aPoint1 is the first point of the segment to test intersection with. + * @param aPoint2 is the second point of the segment to test intersection with. + * @param aIntersection1 will be filled with the first intersection point, if any. + * @param aIntersection2 will be filled with the second intersection point, if any. + * @return true if the segment intersects the rect. */ bool Intersects( const wxPoint& aPoint1, const wxPoint& aPoint2, wxPoint* aIntersection1, wxPoint* aIntersection2 ) const; @@ -265,29 +257,26 @@ public: const wxPoint FarthestPointTo( const wxPoint& aPoint ) const; /** - * Function IntersectsCircle - * tests for a common area between a circle and this rectangle + * Test for a common area between a circle and this rectangle. * - * @param aCenter center of the circle - * @param aRadius radius of the circle + * @param aCenter center of the circle. + * @param aRadius radius of the circle. */ bool IntersectsCircle( const wxPoint& aCenter, const int aRadius ) const; /** - * IntersectsCircleEdge - * Tests for intersection between this rect and the edge (radius) of a circle + * Test for intersection between this rect and the edge (radius) of a circle. * - * @param aCenter center of the circle - * @param aRadius radius of the circle - * @param aWidth width of the circle edge + * @param aCenter center of the circle. + * @param aRadius radius of the circle. + * @param aWidth width of the circle edge. */ bool IntersectsCircleEdge( const wxPoint& aCenter, const int aRadius, const int aWidth ) const; /** - * Function operator(wxRect) - * overloads the cast operator to return a wxRect - * wxRect does not accept negative values for size, so ensure the - * wxRect size is always >= 0 + * Overload the cast operator to return a wxRect. + * + * wxRect does not accept negative values for size, so ensure the wxRect size is always >= 0. */ operator wxRect() const { @@ -297,9 +286,9 @@ public: } /** - * Function operator(BOX2I) - * overloads the cast operator to return a BOX2I - * @return BOX2I - this box shaped as a BOX2I object. + * Overload the cast operator to return a BOX2I. + * + * @return this box shaped as a BOX2I object. */ operator BOX2I() const { @@ -309,56 +298,54 @@ public: } /** - * Function Inflate - * inflates the rectangle horizontally by \a dx and vertically by \a dy. If \a dx + * Inflate the rectangle horizontally by \a dx and vertically by \a dy. If \a dx * and/or \a dy is negative the rectangle is deflated. */ EDA_RECT& Inflate( wxCoord dx, wxCoord dy ); /** - * Function Inflate - * inflates the rectangle horizontally and vertically by \a aDelta. If \a aDelta + * Inflate the rectangle horizontally and vertically by \a aDelta. If \a aDelta * is negative the rectangle is deflated. */ EDA_RECT& Inflate( int aDelta ); /** - * Function Merge - * modifies the position and size of the rectangle in order to contain \a aRect. It is - * mainly used to calculate bounding boxes. + * Modify the position and size of the rectangle in order to contain \a aRect. + * + * It is mainly used to calculate bounding boxes. + * * @param aRect The rectangle to merge with this rectangle. */ void Merge( const EDA_RECT& aRect ); /** - * Function Merge - * modifies the position and size of the rectangle in order to contain the given point. + * Modify the position and size of the rectangle in order to contain the given point. + * * @param aPoint The point to merge with the rectangle. */ void Merge( const wxPoint& aPoint ); /** - * Function GetArea - * returns the area of the rectangle. + * Return the area of the rectangle. + * * @return The area of the rectangle. */ double GetArea() const; /** - * Function Common - * returns the area that is common with another rectangle. + * Return the area that is common with another rectangle. + * * @param aRect is the rectangle to find the common area with. * @return The common area rect or 0-sized rectangle if there is no intersection. */ EDA_RECT Common( const EDA_RECT& aRect ) const; /** - * Function GetBoundingBoxRotated - * @return the bounding box of this, after rotation - * @param aAngle = the rotation angle in 0.1 deg. - * @param aRotCenter = the rotation point. - * useful to calculate bounding box of rotated items, when - * rotation if not k*90 degrees + * Useful to calculate bounding box of rotated items, when rotation if not k*90 degrees. + * + * @return the bounding box of this, after rotation. + * @param aAngle the rotation angle in 0.1 deg. + * @param aRotCenter the rotation point. */ const EDA_RECT GetBoundingBoxRotated( wxPoint aRotCenter, double aAngle ) const; }; diff --git a/include/eda_text.h b/include/eda_text.h index db0a0e1911..2a792d03ae 100644 --- a/include/eda_text.h +++ b/include/eda_text.h @@ -2,7 +2,7 @@ * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2013 Jean-Pierre Charras, jpe.charras at wanadoo.fr - * Copyright (C) 2004-2019 KiCad Developers, see change_log.txt for contributors. + * Copyright (C) 2004-2020 KiCad Developers, see change_log.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License @@ -111,10 +111,10 @@ struct TEXT_EFFECTS /** - * A mix-in class (via multiple inheritance) that handles texts such as - * labels, parts, components, or footprints. Because it's a mix-in class, care - * is used to provide function names (accessors) that to not collide with function - * names likely to be seen in the combined derived classes. + * A mix-in class (via multiple inheritance) that handles texts such as labels, parts, + * components, or footprints. Because it's a mix-in class, care is used to provide + * function names (accessors) that to not collide with function names likely to be seen + * in the combined derived classes. */ class EDA_TEXT { @@ -134,7 +134,8 @@ public: /** * Return the string actually shown after processing of the base text. - * @aParam aDepth is used to prevent infinite recusions and loops when expanding + * + * @param aDepth is used to prevent infinite recursions and loops when expanding * text variables. */ virtual wxString GetShownText( int aDepth = 0 ) const { return m_shown_text; } @@ -142,6 +143,7 @@ public: /** * A version of GetShownText() which also indicates whether or not the text needs * to be processed for text variables. + * * @param processTextVars [out] */ wxString GetShownText( bool* processTextVars ) const @@ -165,8 +167,7 @@ public: int GetTextThickness() const { return m_e.penwidth; }; /** - * The EffectiveTextPenWidth uses the text thickness if > 1 or - * aDefaultWidth. + * The EffectiveTextPenWidth uses the text thickness if > 1 or aDefaultWidth. */ int GetEffectiveTextPenWidth( int aDefaultWidth = 0 ) const; @@ -195,9 +196,8 @@ public: bool IsMirrored() const { return m_e.Bit( TE_MIRROR ); } /** - * @param aAllow true if ok to use multiline option, false - * if ok to use only single line text. (Single line is faster in - * calculations than multiline.) + * @param aAllow true if ok to use multiline option, false if ok to use only single line + * text. (Single line is faster in calculations than multiline.) */ void SetMultilineAllowed( bool aAllow ) { m_e.Bit( TE_MULTILINE, aAllow ); } bool IsMultilineAllowed() const { return m_e.Bit( TE_MULTILINE ); } @@ -211,7 +211,7 @@ public: /** * Set the text effects from another instance. * - * TEXT_EFFECTS is not exposed in the public API, but includes everything except the actual + * #TEXT_EFFECTS is not exposed in the public API, but includes everything except the actual * text string itself. */ void SetEffects( const EDA_TEXT& aSrc ); @@ -219,7 +219,7 @@ public: /** * Swap the text effects of the two involved instances. * - * TEXT_EFFECTS is not exposed in the public API, but includes everything except the actual + * #TEXT_EFFECTS is not exposed in the public API, but includes everything except the actual * text string itself. */ void SwapEffects( EDA_TEXT& aTradingPartner ); @@ -267,10 +267,10 @@ public: /** * Print this text object to the device context \a aDC. * - * @param aDC = the current Device Context - * @param aOffset = draw offset (usually (0,0)) - * @param aColor = text color - * @param aDisplay_mode = FILLED or SKETCH + * @param aDC the current Device Context. + * @param aOffset draw offset (usually (0,0)). + * @param aColor text color. + * @param aDisplay_mode #FILLED or #SKETCH. */ void Print( RENDER_SETTINGS* aSettings, const wxPoint& aOffset, COLOR4D aColor, OUTLINE_MODE aDisplay_mode = FILLED ); @@ -290,9 +290,9 @@ public: * Used in filling zones calculations * Circles and arcs are approximated by segments * - * @param aCornerBuffer = a buffer to store the polygon - * @param aClearanceValue = the clearance around the text bounding box - * to the real clearance value (usually near from 1.0) + * @param aCornerBuffer a buffer to store the polygon. + * @param aClearanceValue the clearance around the text bounding box + * to the real clearance value (usually near from 1.0). */ void TransformBoundingBoxWithClearanceToPolygon( SHAPE_POLY_SET* aCornerBuffer, int aClearanceValue ) const; @@ -302,33 +302,34 @@ public: /** * Test if \a aPoint is within the bounds of this object. * - * @param aPoint- A wxPoint to test - * @param aAccuracy - Amount to inflate the bounding box. - * @return bool - true if a hit, else false + * @param aPoint A wxPoint to test. + * @param aAccuracy Amount to inflate the bounding box. + * @return true if a hit, else false. */ virtual bool TextHitTest( const wxPoint& aPoint, int aAccuracy = 0 ) const; /** * Test if object bounding box is contained within or intersects \a aRect. * - * @param aRect - Rect to test against. - * @param aContains - Test for containment instead of intersection if true. - * @param aAccuracy - Amount to inflate the bounding box. - * @return bool - true if a hit, else false + * @param aRect Rect to test against. + * @param aContains Test for containment instead of intersection if true. + * @param aAccuracy Amount to inflate the bounding box. + * @return true if a hit, else false. */ virtual bool TextHitTest( const EDA_RECT& aRect, bool aContains, int aAccuracy = 0 ) const; /** - * @return the text length in internal units - * @param aLine : the line of text to consider. - * For single line text, this parameter is always m_Text - * @param aThickness : the stroke width of the text + * @return the text length in internal units. + * @param aLine the line of text to consider. For single line text, this parameter + * is always m_Text. + * @param aThickness the stroke width of the text. */ int LenSize( const wxString& aLine, int aThickness ) const; /** * Useful in multiline texts to calculate the full text or a line area (for zones filling, * locate functions....) + * * @param aLine The line of text to consider. Pass -1 for all lines. * @param aInvertY Invert the Y axis when calculating bounding box. * @return the rect containing the line of text (i.e. the position and the size of one line) @@ -347,20 +348,19 @@ public: int GetInterline() const; /** - * @return a wxString with the style name( Normal, Italic, Bold, Bold+Italic) + * @return a wxString with the style name( Normal, Italic, Bold, Bold+Italic). */ wxString GetTextStyleName() const; /** - * Populate \a aPositions with the position of each line of - * a multiline text, according to the vertical justification and the - * rotation of the whole text + * Populate \a aPositions with the position of each line of a multiline text, according + * to the vertical justification and the rotation of the whole text. * - * @param aPositions is the list to populate by the wxPoint positions - * @param aLineCount is the number of lines (not recalculated here - * for efficiency reasons + * @param aPositions is the list to populate by the wxPoint positions. + * @param aLineCount is the number of lines (not recalculated here for efficiency reasons. */ void GetLinePositions( std::vector& aPositions, int aLineCount ) const; + /** * Output the object to \a aFormatter in s-expression form. * @@ -374,6 +374,18 @@ public: virtual double GetDrawRotation() const; private: + /** + * Print each line of this EDA_TEXT.. + * + * @param aOffset draw offset (usually (0,0)). + * @param aColor text color. + * @param aFillMode FILLED or SKETCH + * @param aText the single line of text to draw. + * @param aPos the position of this line ). + */ + void printOneLineOfText( RENDER_SETTINGS* aSettings, const wxPoint& aOffset, COLOR4D aColor, + OUTLINE_MODE aFillMode, const wxString& aText, const wxPoint& aPos ); + wxString m_text; wxString m_shown_text; // Cache of unescaped text for efficient access bool m_shown_text_has_text_var_refs; @@ -387,20 +399,6 @@ private: TE_MULTILINE, TE_VISIBLE, }; - -private: - /** - * Print each line of this EDA_TEXT. - * - * @param aOffset = draw offset (usually (0,0)) - * @param aColor = text color - * @param aFillMode = FILLED or SKETCH - * @param aText = the single line of text to draw. - * @param aPos = the position of this line ). - */ - void printOneLineOfText( RENDER_SETTINGS* aSettings, const wxPoint& aOffset, COLOR4D aColor, - OUTLINE_MODE aFillMode, const wxString& aText, - const wxPoint& aPos ); };