Initial commit with library template

Author: bohnacker

README.md

@@ -0,0 +1,100 @@
+The following describes how to set up a Processing Library project in Eclipse and build it successfully, and to make your Library ready for distribution.
+
+## Import to Eclipse
+
+There are two options to import the template project into Eclipse: using a Git [fork](https://help.github.com/articles/fork-a-repo) or using a downloaded package. If you are not familiar with Git or GitHub, you should opt for the downloaded package.
+
+### Option A: GitHub
+
+1. Fork the template repository to use as a starting point.
+  * Navigate to https://github.com/processing/processing-library-template in your browser.
+  * Click the "Fork" button in the top-right of the page.
+  * Once your fork is ready, open the new repository's "Settings" by clicking the link in the menu bar on the right.
+  * Change the repository name to the name of your Library and save your changes.
+  * NOTE: GitHub only allows you to fork a project once. If you need to create multiple forks, you can follow these [instructions](http://adrianshort.org/2011/11/08/create-multiple-forks-of-a-github-repo/).
+1. Clone your new repository to your Eclipse workspace.
+  * Open Eclipse and select the File → Import... menu item.
+  * Select Git → Projects from Git, and click "Next >".
+  * Select "URI" and click "Next >". 
+  * Enter your repository's clone URL in the "URI" field. The remaining fields in the "Location" and "Connection" groups will get automatically filled in.
+  * Enter your GitHub credentials in the "Authentication" group, and click "Next >".
+  * Select the `master` branch on the next screen, and click "Next >".
+  * The default settings on the "Local Configuration" screen should work fine, click "Next >".
+  * Make sure "Import existing projects" is selected, and click "Next >".
+  * Eclipse should find and select the `processing-library-template` automatically, click "Finish".
+1. Rename your Eclipse project.
+  * In the Package Explorer, right-click (ctrl-click) on the folder icon of the `processing-library-template` project, and select Refactor → Rename... from the menu that pops up. 
+  * Give the project the name of your Library, and click "OK".
+  
+### Option B: Downloaded Package
+
+1. Download the latest Eclipse template from [here](https://github.com/processing/processing-library-template/releases). **Don't unzip the ZIP file yet.**
+1. Create a new Java project in Eclipse. 
+  * From the menubar choose File → New → Java Project. 
+  * Give the project the name of your Library. 
+  * Click "Finish".
+1. Import the template source files.
+  * Right-click (ctrl-click) onto the folder icon of your newly created project in the Package Explorer and select "Import..." from the menu that pops up. 
+  * Select General → Archive File, and click "Next >".
+  * Navigate to the ZIP file you downloaded earlier in step 1, and click "Finish".
+
+## Set Up and Compile
+
+1. Add Processing to the project build path.
+  * Open your project's "Properties" window. 
+  * Under "Java Build Path", select the "Libraries" tab and then "Add External JARs...". 
+  * Locate and add Processing's `core.jar` to your build path. It is recommended that a copy of `core.jar` is located in your Eclipse workspace in a `libs` folder. If the `libs` folder does not exist yet, create it. Read the [section below](#AddingJARs) regarding where to find the `core.jar` file.
+  * Confirm the setup with "OK".
+1. Edit the Library properties.
+  * Open the `resources` folder inside of your Java project and double-click the `build.properties` file. You should see its contents in the Eclipse editor. 
+  * Edit the properties file, making changes to items 1-4 so that the values and paths are properly set for your project to compile. A path can be relative or absolute.
+  * Make changes to items under 5. These are metadata used in the automatically generated HTML, README, and properties documents.
+1. Compile your Library using Ant.
+  * From the menu bar, choose Window → Show View → Ant. A tab with the title "Ant" will pop up on the right side of your Eclipse editor. 
+  * Drag the `resources/build.xml` file in there, and a new item "ProcessingLibs" will appear. 
+  * Press the "Play" button inside the "Ant" tab.
+1. BUILD SUCCESSFUL. The Library template will start to compile, control messages will appear in the console window, warnings can be ignored. When finished it should say BUILD SUCCESSFUL. Congratulations, you are set and you can start writing your own Library by making changes to the source code in folder `src`.
+1. BUILD FAILED. In case the compile process fails, check the output in the console which will give you a closer idea of what went wrong. Errors may have been caused by
+  * Incorrect path settings in the `build.properties` file.
+  * Error "Javadoc failed". if you are on Windows, make sure you are using a JDK instead of a JRE in order to be able to create the Javadoc for your Library. JRE does not come with the Javadoc application, but it is required to create Libraries from this template.
+
+After having compiled and built your project successfully, you should be able to find your Library in Processing's sketchbook folder, examples will be listed in Processing's sketchbook menu. Files that have been created for the distribution of the Library are located in your Eclipse's `workspace/yourProject/distribution` folder. In there you will also find the `web` folder which contains the documentation, a ZIP file for downloading your Library, a folder with examples as well as the `index.html` and CSS file.
+
+To distribute your Library please refer to the [Library Guidelines](https://github.com/processing/processing/wiki/Library-Guidelines).
+
+## Source code
+
+If you want to share your Library's source code, we recommend using an online repository available for free at [GitHub](https://github.com/).
+
+## <a name='AddingJARs'/>Adding core.jar and other .jar files to your classpath</a>
+
+The `core.jar` file contains the core classes of Processing and has to be part of your classpath when building a Library. On Windows and Linux, this file is located in the Processing distribution folder inside a folder named `lib`. On Mac OS X, right-click the Processing.app and use "Show Package Contents" to see the guts. The `core.jar` file is inside Contents → Resources → Java. For further information about the classes in `core.jar`, you can see the source [here](http://code.google.com/p/processing/source/browse/trunk/processing#processing/core) and the developer documentation [here](http://processing.googlecode.com/svn/trunk/processing/build/javadoc/core/index.html).
+
+If you created a `libs` folder as described above, put the libraries you need to add to your classpath in there. In the "Properties" of your Java project, navigate to Java Build Path → Libraries, and click "Add External JARs...". Select the `.jar` files from the `libs` folder that are required for compiling your project. Adjust the `build.xml` file accordingly.
+
+The `libs` folder is recommended but not a requirement, nevertheless you need to specify where your `.jar` files are located in your system in order to add them to the classpath.
+
+In case a Library depends on system libraries, put these dependencies next to the `.jar` file. For example, Processing's `opengl.jar` Library depends on JOGL hence the DLLs (for Windows) or jnilibs (for OS X) have to be located next to the `opengl.jar` file.
+
+## What is the difference between JDK and JRE?
+
+JDK stands for Java Development Kit whereas JRE stands for Java Runtime Environment. For developers it is recommended to work with a JDK instead of a JRE since more Java development related applications such as Javadoc are included. Javadoc is a requirement to properly compile and document a Processing Library as described on the guidelines page.
+
+You can have both a JDK and a JRE installed on your system. In Eclipse you need to specify which one you want to use.
+
+## The JRE System Library
+
+This primarily affects Windows and Linux users (because the full JDK is installed by default on Mac OS X). It is recommended that you use the JDK instead of a JRE. The JDK can be downloaded from [Oracle's download site](http://www.oracle.com/technetwork/java/javase/downloads/index.html). Also see the [Java Platform Installation page](http://www.oracle.com/technetwork/java/javase/index-137561.html), which contains useful information.
+
+To change the JRE used to compile your Java project:
+
+1. Open the properties of your project from the menu Project → Properties. Select "Java Build Path" and in its submenu, click on the "Libraries" tab.
+1. A list of JARs and class folders in the build path will show up. In this list you can find the JRE System Library that is used to compile your code. Remove this JRE System library.
+1. Click "Add Library...". In the popup window, choose "JRE System Library" and press "Next".
+1. Select an alternate JRE from the pull-down menu or click and modify the "Installed JREs". Confirm with "Finish" and "OK". 
+
+## Compiling with Ant and javadoc
+
+Ant is a Java-based build tool. For [more information](http://ant.apache.org/faq.html#what-is-ant) visit the [Ant web site](http://ant.apache.org/). Ant uses a file named `build.xml` to store build settings for a project.
+
+Javadoc is an application that creates an HTML-based API documentation of Java code. You can check for its existence by typing `javadoc` on the command line. On Mac OS X, it is installed by default. On Windows and Linux, installing the JDK will also install the Javadoc tool. 

bin/template/library/HelloLibrary.class

@@ -0,0 +1,7 @@
+the data folder:
+If your Library is using files like images, sound files, 
+any data file, etc., put them into the data folder. 
+When coding your Library you can use processing's internal loading 
+functions like loadImage(), loadStrings(), etc. to load files 
+located inside the data folder into your Library.
+

data/README

@@ -0,0 +1,19 @@
+import template.library.*;
+
+HelloLibrary hello;
+
+void setup() {
+  size(400,400);
+  smooth();
+  
+  hello = new HelloLibrary(this);
+  
+  PFont font = createFont("",40);
+  textFont(font);
+}
+
+void draw() {
+  background(0);
+  fill(255);
+  text(hello.sayHello(), 40, 200);
+}

examples/Hello/Hello.pde

@@ -0,0 +1 @@
+add examples for your Library here.

examples/README

@@ -0,0 +1,6 @@
+The lib folder:
+In case your Library requires 3rd party libraries, which need to be 
+added to the distribution, put them into the lib folder. 
+These 3rd party libraries will be added to your distribution and are 
+located next to your Library's jar file.
+This does not apply to .jar files that are considered core processing libraries.

lib/README

@@ -0,0 +1,18 @@
+A template to build a Library for the Processing programming environment.
+
+Part of the Processing project - http://processing.org
+
+Copyright 2011-2015 Elie Zananiri
+Copyright 2008-2011 Andreas Shlegel
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

license.txt

@@ -0,0 +1,38 @@
+## How to install ##library.name##
+
+### Install with the Contribution Manager
+
+Add contributed Libraries by selecting the menu item _Sketch_ → _Import Library..._ → _Add Library..._ This will open the Contribution Manager, where you can browse for ##library.name##, or any other Library you want to install.
+
+Not all available Libraries have been converted to show up in this menu. If a Library isn't there, it will need to be installed manually by following the instructions below.
+
+### Manual Install
+
+Contributed Libraries may be downloaded separately and manually placed within the `libraries` folder of your Processing sketchbook. To find (and change) the Processing sketchbook location on your computer, open the Preferences window from the Processing application (PDE) and look for the "Sketchbook location" item at the top.
+
+By default the following locations are used for your sketchbook folder: 
+  * For Mac users, the sketchbook folder is located inside `~/Documents/Processing` 
+  * For Windows users, the sketchbook folder is located inside `My Documents/Processing`
+
+Download ##library.name## from ##library.url##
+
+Unzip and copy the contributed Library's folder into the `libraries` folder in the Processing sketchbook. You will need to create this `libraries` folder if it does not exist.
+
+The folder structure for Library ##library.name## should be as follows:
+
+```
+Processing
+  libraries
+    ##library.name##
+      examples
+      library
+        ##library.name##.jar
+      reference
+      src
+```
+             
+Some folders like `examples` or `src` might be missing. After Library ##library.name## has been successfully installed, restart the Processing application.
+
+### Troubleshooting
+
+If you're having trouble, have a look at the [Processing Wiki](https://github.com/processing/processing/wiki/How-to-Install-a-Contributed-Library) for more information, or contact the author [##author.name##](##author.url##).

resources/README.md

@@ -0,0 +1,171 @@
+# Create a Library for the Processing open source programming language and 
+# environment (http://processing.org/)
+#
+# Customize the build properties to make the ant-build-process work for your 
+# environment. How? Please read the comments below.
+#
+# The default properties are set for OS X. Please refer to comments for Windows
+# settings.
+
+
+# Where is your Processing sketchbook located? 
+# If you are not sure, check the sketchbook location in your Processing 
+# application preferences.
+# ${user.home} points the compiler to your home directory.
+# For windows the default path to your sketchbook would be
+# ${user.home}/My Documents/Processing (make adjustments below)
+
+#sketchbook.location=${user.home}/My Documents/Processing
+sketchbook.location=${user.home}/Documents/Processing
+
+
+# Where are the jar files located that are required for compiling your Library 
+# such as e.g. core.jar?
+# By default the local classpath location points to folder libs inside Eclipse's
+# workspace (by default found in your home directory).
+# For Windows, the default path would be
+# ${user.home}/Documents/workspace/libs (make adjustments below)
+# For OS X,the following path will direct you into Processing's application
+# package, in case you put Processing inside your Applications folder. 
+
+#classpath.local.location=${user.home}/Documents/workspace/libs
+classpath.local.location=/Applications/Processing.app/Contents/Java/core/library
+
+
+# Add all jar files that are required for compiling your project to the local 
+# and project classpath. Use a comma as delimiter. These jar files must be 
+# inside your classpath.local.location folder.
+
+classpath.local.include=core.jar
+
+
+# Add processing's libraries folder to the classpath.
+# If you don't need to include the libraries folder to your classpath, comment 
+# out the following line.
+
+classpath.libraries.location=${sketchbook.location}/libraries
+
+
+# Set the java version that should be used to compile your Library.
+
+java.target.version=1.7
+
+
+# Set the description of the Ant build.xml file.
+
+ant.description=Processing Library Ant build file.
+
+
+# Give your Library a name. The name must not contain spaces or special 
+# characters.
+
+project.name=YourLibrary
+
+
+# The name as the user will see it. This can contain spaces and special 
+# characters.
+
+project.prettyName=Your Library
+
+
+# Use 'normal' or 'fast' as value for project.compile.
+# 'fast' will only compile the project into your sketchbook.
+# 'normal' will compile the distribution including the javadoc-reference and all
+# web-files (the compile process here takes longer).
+# All files compiled with project.compile=normal are stored in the distribution 
+# folder.
+
+project.compile=normal
+
+
+# Set your name and URL, used for the web page and properties file.
+
+author.name=Your Name
+author.url=http://yoururl.com
+
+
+# Set the web page for your Library.
+# This is NOT a direct link to where to download it.
+
+library.url=http://yourlibraryname.com
+
+
+# Set the category (or categories) of your Library from the following list:
+#   "3D"            "Animation"     "Compilations"      "Data"          
+#   "Fabrication"   "Geometry"      "GUI"               "Hardware"      
+#   "I/O"           "Language"      "Math"              "Simulation"    
+#   "Sound"         "Utilities"     "Typography"        "Video & Vision"
+# 
+# If a value other than those listed is used, your Library will listed as 
+# "Other". Many categories must be comma-separated.
+
+library.categories=Other
+
+
+# A short sentence (or fragment) to summarize the Library's function. This will 
+# be shown from inside the PDE when the Library is being installed. Avoid 
+# repeating the name of your Library here. Also, avoid saying anything redundant 
+# like mentioning that it's a Library. This should start with a capitalized 
+# letter, and end with a period.
+
+library.sentence=A collection of utilities for solving this and that problem.
+
+
+# Additional information suitable for the Processing website. The value of
+# 'sentence' always will be prepended, so you should start by writing the
+# second sentence here. If your Library only works on certain operating systems,
+# mention it here.
+
+library.paragraph= 
+
+
+# Set the source code repository for your project.
+# Recommendations for storing your source code online are GitHub or Google Code.
+
+source.host=GitHub
+source.url=https://github.com/YourName/YourProject
+source.repository=https://github.com/YourName/YourProject.git
+
+
+# The current version of your Library. 
+# This number must be parsable as an int. It increments once with each release. 
+# This is used to compare different versions of the same Library, and check if 
+# an update is available.
+
+library.version=1
+
+
+# The version as the user will see it.
+
+library.prettyVersion=1.0.0
+
+
+# The min and max revision of Processing compatible with your Library.
+# Note that these fields use the revision and not the version of Processing, 
+# parsable as an int. For example, the revision number for 2.2.1 is 227. 
+# You can find the revision numbers in the change log: https://raw.githubusercontent.com/processing/processing/master/build/shared/revisions.txt
+# Only use maxRevision (or minRevision), when your Library is known to 
+# break in a later (or earlier) release. Otherwise, use the default value 0.
+
+compatible.minRevision=0
+compatible.maxRevision=0
+
+
+# The platforms and Processing version that the Library has been tested
+# against. This information is only used in the generated webpage.
+
+tested.platform=osx,windows
+tested.processingVersion=3.0
+
+
+# Additional information for the generated webpage.
+
+library.copyright=(c) 2015
+library.dependencies=?
+library.keywords=?
+
+
+# Include javadoc references into your project's javadocs.
+
+javadoc.java.href=http://docs.oracle.com/javase/7/docs/api/
+javadoc.processing.href=http://processing.org/reference/javadoc/core/