/* * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2012 Brian Sidebotham * Copyright The 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 * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, you may find one here: * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html * or you may search the http://www.gnu.org website for the version 2 license, * or you may write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA */ /** @page prj_tmp Project Templates Author: Brian Sidebotham Proposal -------- To add new project template functionality to KiCad to facilitate the easy setup of projects which have common attributes such as pre-defined board outlines, connector positions, schematic elements, design rules, etc. Definitions ----------- A template is a directory of files, which includes a directory of metadata. The template system name (SYSNAME) is the directory name under which the template files are stored. The metadata directory (METADIR) contains pre-defined files which provide information about the template. All files and directories in a template are copied to the new project path when a project is created using a template, except METADIR. All files and directories which start with SYSNAME will have SYSNAME replaced by the new project file name, excluding the file extension. Metadata -------- A template's METADIR must contain the required files, and might optionally contain any of the optional files Required Files ~~~~~~~~~~~~~~ /info.html - Contains html formatted information about the template which is used by the user to determine if the template is what they are after. The <title> tag determines the actual name of the template that is exposed to the user for template selection. Using html to format this document means that images can be in-lined without having to invent a new scheme. Only HTML supported by wxHTML can be used to format this document. Optional Files ~~~~~~~~~~~~~~ /icon.png - A 64 x 64px PNG icon file which is used as a clickable icon in the template selection dialog. Operation --------- The KiCad File menu will be modified to change New from a menu item to a pop-out menu item, in the same manor as Open Recent. There will be two options on the pop-out menu: Blank -> Will act exactly the same as the current new menu item so that anyone who wishes to create a blank project won't have their settings lost or feel alienated. From Template -> Will open the template selection dialog. The template selection dialog will have a list of icons on the left, and a wxHTML window to the right. A single click on a template's icon on the left will load that templates info.html metadata file and display it in the wxHTML window. A double click on a template's icon will start the new project creation and will open a new file dialog. If the user selects a valid location for the new project, the template will be copied to the new project location ( excluding METADIR as mentioned earlier ) and any files that match the string replacement rules will be renamed to reflect the new project's name. The list of available templates will be gathered from the following sources: wxStandardPaths::GetExecutableDir()/../share/template/ wxStandardPaths::GetUserDataDir()/templates/ wxGetEnv(wxT("KICAD_PTEMPLATES")) wxGetEnv(wxT("KICAD"))/template/ */ #ifndef PROJECT_TEMPLATE_H #define PROJECT_TEMPLATE_H #include #include #include class wxBitmap; class wxFileName; /** * A directory which contains information about the project template and does not get * copied. This define is the default filename for this directory * */ #define METADIR wxT( "meta" ) /** * A required html formatted file which contains information about the project template. * This define is the default filename for this file * */ #define METAFILE_INFO_HTML wxT( "info.html" ) /** * An optional png icon, exactly 64px x 64px which is used in the template selector if * present. This define is the default filename for this file * */ #define METAFILE_ICON wxT( "icon.png" ) /** * A class which provides project template functionality. */ class PROJECT_TEMPLATE { protected: wxFileName m_basePath; wxFileName m_metaPath; wxFileName m_metaHtmlFile; wxFileName m_metaIconFile; wxBitmap* m_metaIcon; wxString m_title; public: /** * Create a new project instance from \a aPath. \a aPath should be a directory that * conforms to the project template requirements * * @param aPath Should be a directory containing the template */ PROJECT_TEMPLATE( const wxString& aPath ); /** * Non-virtual destructor (so no derived classes) */ ~PROJECT_TEMPLATE(); /** * Get the dir name of the project template (i.e. the name of the last folder containing * the template files) * * @return the dir name of the template */ wxString GetPrjDirName(); /** * Get the full Html filename for the project template * * @return the html meta information file for this template */ wxFileName GetHtmlFile(); /** * Copies and renames all template files to create a new project. * * @param aNewProjectPath The full path of the new project file to create * @param aErrorMsg is an optional string to place project creation error messages. * @return true if the project creation was successful otherwise false. */ bool CreateProject( wxFileName& aNewProjectPath, wxString* aErrorMsg = nullptr ); /** * Get the 64px^2 icon for the project template * * @return an image file of 64px x 64px which is the templates icon */ wxBitmap* GetIcon(); /** * Get the title of the project (extracted from the html title tag) */ wxString* GetTitle(); /** * Get a vector list of filenames for the template. The files are the source files, * and have not yet been through any renaming */ std::vector GetFileList(); /** * Fetch the list of destination files to be copied when the new project is created. * * @param aNewProjectPath is the path to the project to be created. * @param aDestFiles is a container to place the list of destination files to be created. * @return the number of destination files added to the container. */ size_t GetDestinationFiles( const wxFileName& aNewProjectPath, std::vector< wxFileName >& aDestFiles ); }; #endif