diff --git a/core/src/processing/core/PApplet.java b/core/src/processing/core/PApplet.java index 2452a441d..a05a17c3d 100644 --- a/core/src/processing/core/PApplet.java +++ b/core/src/processing/core/PApplet.java @@ -140,9 +140,9 @@ import javax.swing.SwingUtilities; * * *

Processing on multiple displays

- *

I was asked about Processing with multiple displays, and for lack of a + *

I was asked about Processing with multiple displays, and for lack of a * better place to document it, things will go here.

- *

You can address both screens by making a window the width of both, + *

You can address both screens by making a window the width of both, * and the height of the maximum of both screens. In this case, do not use * present mode, because that's exclusive to one screen. Basically it'll * give you a PApplet that spans both screens. If using one half to control @@ -150,7 +150,7 @@ import javax.swing.SwingUtilities; * on one half of the canvas, the control stuff on the other. This works * better in windows because on the mac we can't get rid of the menu bar * unless it's running in present mode.

- *

For more control, you need to write straight java code that uses p5. + *

For more control, you need to write straight java code that uses p5. * You can create two windows, that are shown on two separate screens, * that have their own PApplet. this is just one of the tradeoffs of one of * the things that we don't support in p5 from within the environment @@ -173,7 +173,7 @@ public class PApplet extends Applet /** * Version of Java that's in use, whether 1.1 or 1.3 or whatever, * stored as a float. - *

+ *

* Note that because this is stored as a float, the values may * not be exactly 1.3 or 1.4. Instead, make sure you're * comparing against 1.3f or 1.4f, which will have the same amount @@ -186,7 +186,7 @@ public class PApplet extends Applet /** * Current platform in use. - *

+ *

* Equivalent to System.getProperty("os.name"), just used internally. */ @@ -256,7 +256,10 @@ public class PApplet extends Applet /** * ( begin auto-generated from screenWidth.xml ) * - * System variable which stores the width of the computer screen. For example, if the current screen resolution is 1024x768, + * System variable which stores the width of the computer screen. For example, if the current screen resolution is 1024x768, screenWidth is 1024 and screenHeight is 768. These dimensions are useful when exporting full-screen applications. + *

+ * To ensure that the sketch takes over the entire screen, use "Present" instead of "Run". Otherwise the window will still have a frame border around it and not be placed in the upper corner of the screen. On Mac OS X, the menu bar will remain present unless "Present" mode is used. + * * ( end auto-generated ) */ public int screenWidth; @@ -264,7 +267,10 @@ public class PApplet extends Applet /** * ( begin auto-generated from screenHeight.xml ) * - * System variable that stores the height of the computer screen. For example, if the current screen resolution is 1024x768, + * System variable that stores the height of the computer screen. For example, if the current screen resolution is 1024x768, screenWidth is 1024 and screenHeight is 768. These dimensions are useful when exporting full-screen applications. + *

+ * To ensure that the sketch takes over the entire screen, use "Present" instead of "Run". Otherwise the window will still have a frame border around it and not be placed in the upper corner of the screen. On Mac OS X, the menu bar will remain present unless "Present" mode is used. + * * ( end auto-generated ) */ public int screenHeight; @@ -276,7 +282,7 @@ public class PApplet extends Applet /** * Command line options passed in from main(). - *

+ *

* This does not include the arguments passed in to PApplet itself. */ public String args[]; @@ -303,7 +309,7 @@ public class PApplet extends Applet /** * Exception thrown when size() is called the first time. - *

+ *

* This is used internally so that setup() is forced to run twice * when the renderer is changed. This is the only way for us to handle * invoking the new renderer while also in the midst of rendering. @@ -323,7 +329,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from pixels.xml ) * - * Array containing the values for all the pixels in the display window. These values are of the color datatype. This array is the size of the display window. For example, if the image is 100x100 pixels, there will be 10000 values and if the window is 200x300 pixels, there will be 60000 values. The + * Array containing the values for all the pixels in the display window. These values are of the color datatype. This array is the size of the display window. For example, if the image is 100x100 pixels, there will be 10000 values and if the window is 200x300 pixels, there will be 60000 values. The index value defines the position of a value within the array. For example, the statment color b = pixels[230] will set the variable b to be equal to the value at that location in the array.

Before accessing this array, the data must loaded with the loadPixels() function. After the array data has been modified, the updatePixels() function must be run to update the changes. Without loadPixels(), running the code may (or will in future releases) result in a NullPointerException. + * * ( end auto-generated ) * * @webref image:pixels @@ -338,7 +345,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from width.xml ) * - * System variable which stores the width of the display window. This value is set by the first parameter of the + * System variable which stores the width of the display window. This value is set by the first parameter of the size() function. For example, the function call size(320, 240) sets the width variable to the value 320. The value of width is zero until size() is called. + * * ( end auto-generated ) * @webref environment * @see height @@ -348,7 +356,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from height.xml ) * - * System variable which stores the height of the display window. This value is set by the second parameter of the + * System variable which stores the height of the display window. This value is set by the second parameter of the size() function. For example, the function call size(320, 240) sets the height variable to the value 240. The value of height is zero until size() is called. + * * ( end auto-generated ) * @webref environment * @see width @@ -358,7 +367,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mouseX.xml ) * - * The system variable + * The system variable mouseX always contains the current horizontal coordinate of the mouse. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#mouseY @@ -374,7 +384,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mouseY.xml ) * - * The system variable + * The system variable mouseY always contains the current vertical coordinate of the mouse. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#mouseX @@ -389,7 +400,10 @@ public class PApplet extends Applet /** * ( begin auto-generated from pmouseX.xml ) * - * The system variable + * The system variable pmouseX always contains the horizontal position of the mouse in the frame previous to the current frame.
+ *
+ * You may find that pmouseX and pmouseY have different values inside draw() and inside events like mousePressed() and mouseMoved(). This is because they're used for different roles, so don't mix them! Inside draw(), pmouseX and pmouseY update only once per frame (once per trip through your draw()). But, inside mouse events, they update each time the event is called. If they weren't separated, then the mouse would be read only once per frame, making response choppy. If the mouse variables were always updated multiple times per frame, using line(pmouseX, pmouseY, mouseX, mouseY) inside draw() would have lots of gaps, because pmouseX may have changed several times in between the calls to line(). Use pmouseX and pmouseY inside draw() if you want values relative to the previous frame. Use pmouseX and pmouseY inside the mouse functions if you want continuous response. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#pmouseY @@ -401,7 +415,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from pmouseY.xml ) * - * The system variable + * The system variable pmouseY always contains the vertical position of the mouse in the frame previous to the current frame. More detailed information about how pmouseY is updated inside of draw() and mouse events is explained in the reference for pmouseX. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#pmouseX @@ -428,7 +443,7 @@ public class PApplet extends Applet /** * Used to set pmouseX/Y to mouseX/Y the first time mouseX/Y are used, * otherwise pmouseX/Y are always zero, causing a nasty jump. - *

+ *

* Just using (frameCount == 0) won't work since mouseXxxxx() * may not be called until a couple frames into things. */ @@ -437,7 +452,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mouseButton.xml ) * - * Processing automatically tracks if the mouse button is pressed and which button is pressed. The value of the system variable + * Processing automatically tracks if the mouse button is pressed and which button is pressed. The value of the system variable mouseButton is either LEFT, RIGHT, or CENTER depending on which button is pressed. + * * ( end auto-generated ) * *

Advanced:

@@ -458,7 +474,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mousePressed_var.xml ) * - * Variable storing if a mouse button is pressed. The value of the system variable + * Variable storing if a mouse button is pressed. The value of the system variable mousePressed is true if a mouse button is pressed and false if a button is not pressed. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#mouseX @@ -473,14 +490,19 @@ public class PApplet extends Applet /** * ( begin auto-generated from key.xml ) * - * The system variable + * The system variable key always contains the value of the most recent key on the keyboard that was used (either pressed or released). + *

+ * For non-ASCII keys, use the keyCode variable. The keys included in the ASCII specification (BACKSPACE, TAB, ENTER, RETURN, ESC, and DELETE) do not require checking to see if they key is coded, and you should simply use the key variable instead of keyCode If you're making cross-platform projects, note that the ENTER key is commonly used on PCs and Unix and the RETURN key is used instead on Macintosh. Check for both ENTER and RETURN to make sure your program will work for all platforms. + * * ( end auto-generated ) + * *

Advanced

* * Last key pressed. - *

+ *

* If it's a coded key, i.e. UP/DOWN/CTRL/SHIFT/ALT, * this will be set to CODED (0xffff or 65535). + * * @webref input:keyboard * @see PApplet#keyCode * @see PApplet#keyPressed @@ -492,15 +514,21 @@ public class PApplet extends Applet /** * ( begin auto-generated from keyCode.xml ) * - * The variable + * The variable keyCode is used to detect special keys such as the UP, DOWN, LEFT, RIGHT arrow keys and ALT, CONTROL, SHIFT. When checking for these keys, it's first necessary to check and see if the key is coded. This is done with the conditional "if (key == CODED)" as shown in the example. + *

+ * The keys included in the ASCII specification (BACKSPACE, TAB, ENTER, RETURN, ESC, and DELETE) do not require checking to see if they key is coded, and you should simply use the key variable instead of keyCode If you're making cross-platform projects, note that the ENTER key is commonly used on PCs and Unix and the RETURN key is used instead on Macintosh. Check for both ENTER and RETURN to make sure your program will work for all platforms. + *

+ * For users familiar with Java, the values for UP and DOWN are simply shorter versions of Java's KeyEvent.VK_UP and KeyEvent.VK_DOWN. Other keyCode values can be found in the Java KeyEvent reference. + * * ( end auto-generated ) * *

Advanced

* When "key" is set to CODED, this will contain a Java key code. - *

+ *

* For the arrow keys, keyCode will be one of UP, DOWN, LEFT and RIGHT. * Also available are ALT, CONTROL and SHIFT. A full set of constants * can be obtained from java.awt.event.KeyEvent, from the VK_XXXX variables. + * * @webref input:keyboard * @see PApplet#key * @see PApplet#keyPressed @@ -512,7 +540,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from keyPressed_var.xml ) * - * The boolean system variable + * The boolean system variable keyPressed is true if any key is pressed and false if no keys are pressed. + * * ( end auto-generated ) * @webref input:keyboard * @see PApplet#key @@ -549,7 +578,7 @@ public class PApplet extends Applet /** * Time in milliseconds when the applet was started. - *

+ *

* Used by the millis() function. */ long millisOffset = System.currentTimeMillis(); @@ -557,7 +586,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from frameRate_var.xml ) * - * The system variable + * The system variable frameRate contains the approximate frame rate of the software as it executes. The initial value is 10 fps and is updated with each frame. The value is averaged (integrated) over several frames. As such, this value won't be valid until after 5-10 frames. + * * ( end auto-generated ) * @webref environment * @see PApplet#frameRate() @@ -578,7 +608,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from frameCount.xml ) * - * The system variable + * The system variable frameCount contains the number of frames displayed since the program started. Inside setup() the value is 0 and and after the first iteration of draw it is 1, etc. + * * ( end auto-generated ) * @webref environment * @see PApplet#frameRate() @@ -618,7 +649,7 @@ public class PApplet extends Applet /** * Location for where to position the applet window on screen. - *

+ *

* This is used by the editor to when saving the previous applet * location, or could be used by other classes to launch at a * specific position on-screen. @@ -641,7 +672,7 @@ public class PApplet extends Applet /** * Allows the user or PdeEditor to set a specific sketch folder path. - *

+ *

* Used by PdeEditor to pass in the location where saveFrame() * and all that stuff should write things. */ @@ -657,7 +688,7 @@ public class PApplet extends Applet /** * When run externally to a PDE Editor, this is sent by the applet * whenever the window is moved. - *

+ *

* This is used so that the editor can re-open the sketch window * in the same position as the user last left it. */ @@ -1082,6 +1113,35 @@ public class PApplet extends Applet /** * ( begin auto-generated from size.xml ) * + * Defines the dimension of the display window in units of pixels. The size() function must be the first line in setup(). If size() is not called, the default size of the window is 100x100 pixels. The system variables width and height are set by the parameters passed to the size() function.

+ * + * Do not use variables as the parameters to size() command, because it will cause problems when exporting your sketch. When variables are used, the dimensions of your sketch cannot be determined during export. Instead, employ numeric values in the size() statement, and then use the built-in width and height variables inside your program when you need the dimensions of the display window are needed.

+ * + * The size() command can only be used once inside a sketch, and cannot be used for resizing.

+ * + * The MODE parameters selects which rendering engine to use. For example, if you will be drawing 3D shapes for the web use P3D, if you want to export a program with OpenGL graphics acceleration use OPENGL. A brief description of the four primary renderers follows:

+ * + * JAVA2D - The default renderer. This renderer supports two dimensional drawing and provides higher image quality in overall, but generally slower than P2D.

+ * + * P2D (Processing 2D) - Fast 2D renderer, best used with pixel data, but not as accurate as the JAVA2D default.

+ * + * P3D (Processing 3D) - Fast 3D renderer for the web. Sacrifices rendering quality for quick 3D drawing.

+ * + * OPENGL - High speed 3D graphics renderer that makes use of OpenGL-compatible graphics hardware is available. Keep in mind that OpenGL is not magic pixie dust that makes any sketch faster (though it's close), so other rendering options may produce better results depending on the nature of your code. Also note that with OpenGL, all graphics are smoothed: the smooth() and noSmooth() commands are ignored.

+ * + * PDF - The PDF renderer draws 2D graphics directly to an Acrobat PDF file. This produces excellent results when you need vector shapes for high resolution output or printing. You must first use Import Library → PDF to make use of the library. More information can be found in the PDF library reference. + * + * If you're manipulating pixels (using methods like get() or blend(), or manipulating the pixels[] array), P2D and P3D will usually be faster than the default (JAVA2D) setting, and often the OPENGL setting as well. Similarly, when handling lots of images, or doing video playback, P2D and P3D will tend to be faster.

+ * + * The P2D, P3D, and OPENGL renderers do not support strokeCap() or strokeJoin(), which can lead to ugly results when using strokeWeight(). (Bug 955)

+ * + * For the most elegant and accurate results when drawing in 2D, particularly when using smooth(), use the JAVA2D renderer setting. It may be slower than the others, but is the most complete, which is why it's the default. Advanced users will want to switch to other renderers as they learn the tradeoffs.

+ * + * Rendering graphics requires tradeoffs between speed, accuracy, and general usefulness of the available features. None of the renderers are perfect, so we provide multiple options so that you can decide what tradeoffs make the most sense for your project. We'd prefer all of them to have perfect visual accuracy, high performance, and support a wide range of features, but that's simply not possible.

+ * + * The maximum width and height is limited by your operating system, and is usually the width and height of your actual screen. On some machines it may simply be the number of pixels on your current screen, meaning that a screen that's 800x600 could support size(1600, 300), since it's the same number of pixels. This varies widely so you'll have to try different rendering modes and sizes until you get what you're looking for. If you need something larger, use createGraphics to create a non-visible drawing surface. + *

+ * Again, the size() method must be the first line of the code (or first item inside setup). Any code that appears before the size() command may run more than once, which can lead to confusing results. * * ( end auto-generated ) *

Advanced

@@ -1160,7 +1220,12 @@ public class PApplet extends Applet /** * ( begin auto-generated from createGraphics.xml ) * - * Creates and returns a new + * Creates and returns a new PGraphics object of the types P2D, P3D, and JAVA2D. Use this class if you need to draw into an off-screen graphics buffer. It's not possible to use createGraphics() with OPENGL, because it doesn't allow offscreen use. The PDF renderer requires the filename parameter. The DXF renderer should not be used with createGraphics(), it's only built for use with beginRaw() and endRaw(). + *

+ * It's important to call any drawing commands between beginDraw() and endDraw() statements. This is also true for any commands that affect drawing, such as smooth() or colorMode(). + *

+ * Unlike the main drawing surface which is completely opaque, surfaces created with createGraphics() can have transparency. This makes it possible to draw into a graphics and maintain the alpha channel. By using save() to write a PNG or TGA file, the transparency of the graphics object will be honored. Note that transparency levels are binary: pixels are either complete opaque or transparent. For the time being (as of release 1.2.1), this means that text characters will be opaque blocks. This will be fixed in a future release (Issue 80). + * * ( end auto-generated ) *

Advanced

* Create an offscreen PGraphics object for drawing. This can be used @@ -1378,7 +1443,12 @@ public class PApplet extends Applet /** * ( begin auto-generated from createImage.xml ) * - * Creates a new PImage (the datatype for storing images). This provides a fresh buffer of pixels to play with. Set the size of the buffer with the + * Creates a new PImage (the datatype for storing images). This provides a fresh buffer of pixels to play with. Set the size of the buffer with the width and height parameters. The format parameter defines how the pixels are stored. See the PImage reference for more information. + *

+ * Be sure to include all three parameters, specifying only the width and height (but no format) will produce a strange error. + *

+ * Advanced users please note that createImage() should be used instead of the syntax new PImage(). + * * ( end auto-generated ) *

Advanced

* Preferred method of creating new PImage objects, ensures that a @@ -1905,7 +1975,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mousePressed.xml ) * - * The + * The mousePressed() function is called once after every time a mouse button is pressed. The mouseButton variable (see the related reference entry) can be used to determine which button has been pressed. + * * ( end auto-generated ) *

Advanced

* @@ -1928,7 +1999,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mouseReleased.xml ) * - * The + * The mouseReleased() function is called every time a mouse button is released. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#mouseX @@ -1943,7 +2015,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mouseClicked.xml ) * - * The + * The mouseClicked() function is called once after a mouse button has been pressed and then released. + * * ( end auto-generated ) *

Advanced

* When the mouse is clicked, mousePressed() will be called, @@ -1963,7 +2036,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mouseDragged.xml ) * - * The + * The mouseDragged() function is called once every time the mouse moves and a mouse button is pressed. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#mouseX @@ -1978,7 +2052,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from mouseMoved.xml ) * - * The + * The mouseMoved() function is called every time the mouse moves and a mouse button is not pressed. + * * ( end auto-generated ) * @webref input:mouse * @see PApplet#mouseX @@ -2084,7 +2159,12 @@ public class PApplet extends Applet * * ( begin auto-generated from keyPressed.xml ) * - * The + * The keyPressed() function is called once every time a key is pressed. The key that was pressed is stored in the key variable. + *

+ * For non-ASCII keys, use the keyCode variable. The keys included in the ASCII specification (BACKSPACE, TAB, ENTER, RETURN, ESC, and DELETE) do not require checking to see if they key is coded, and you should simply use the key variable instead of keyCode If you're making cross-platform projects, note that the ENTER key is commonly used on PCs and Unix and the RETURN key is used instead on Macintosh. Check for both ENTER and RETURN to make sure your program will work for all platforms. + *

+ * Because of how operating systems handle key repeats, holding down a key may cause multiple calls to keyPressed() (and keyReleased() as well). The rate of repeat is set by the operating system and how each computer is configured. + * * ( end auto-generated ) *

Advanced

* @@ -2092,7 +2172,7 @@ public class PApplet extends Applet * Because of how operating systems handle key repeats, holding * down a key will cause multiple calls to keyPressed(), because * the OS repeat takes over. - *

+ *

* Examples for key handling: * (Tested on Windows XP, please notify if different on other * platforms, I have a feeling Mac OS and Linux may do otherwise) @@ -2145,7 +2225,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from keyReleased.xml ) * - * The + * The keyReleased() function is called once every time a key is released. The key that was released will be stored in the key variable. See key and keyReleased for more information. + * * ( end auto-generated ) * @webref input:keyboard * @see PApplet#key @@ -2159,7 +2240,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from keyTyped.xml ) * - * The + * The keyTyped() function is called once every time a key is pressed, but action keys such as Ctrl, Shift, and Alt are ignored. Because of how operating systems handle key repeats, holding down a key will cause multiple calls to keyTyped(), the rate is set by the operating system and how each computer is configured. + * * ( end auto-generated ) * @webref input:keyboard * @see PApplet#keyPressed @@ -2206,7 +2288,7 @@ public class PApplet extends Applet * ( end auto-generated ) * *

Advanced

- *

+ *

* This is a function, rather than a variable, because it may * change multiple times per frame. * @@ -2226,7 +2308,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from second.xml ) * - * Processing communicates with the clock on your computer. The + * Processing communicates with the clock on your computer. The second() function returns the current second as a value from 0 - 59. + * * ( end auto-generated ) * @webref input:time_date * @see PApplet#millis() @@ -2243,7 +2326,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from minute.xml ) * - * Processing communicates with the clock on your computer. The + * Processing communicates with the clock on your computer. The minute() function returns the current minute as a value from 0 - 59. + * * ( end auto-generated ) * * @webref input:time_date @@ -2262,11 +2346,12 @@ public class PApplet extends Applet /** * ( begin auto-generated from hour.xml ) * - * Processing communicates with the clock on your computer. The + * Processing communicates with the clock on your computer. The hour() function returns the current hour as a value from 0 - 23. + * * ( end auto-generated ) *

Advanced

* Hour position of the current time in international format (0-23). - *

+ *

* To convert this value to American time:
* 

int yankeeHour = (hour() % 12);
    * if (yankeeHour == 0) yankeeHour = 12;
@@ -2287,11 +2372,12 @@ public class PApplet extends Applet /** * ( begin auto-generated from day.xml ) * - * Processing communicates with the clock on your computer. The + * Processing communicates with the clock on your computer. The day() function returns the current day as a value from 1 - 31. + * * ( end auto-generated ) *

Advanced

* Get the current day of the month (1 through 31). - *

+ *

* If you're looking for the day of the week (M-F or whatever) * or day of the year (1..365) then use java's Calendar.get() * @@ -2310,7 +2396,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from month.xml ) * - * Processing communicates with the clock on your computer. The + * Processing communicates with the clock on your computer. The month() function returns the current month as a value from 1 - 12. + * * ( end auto-generated ) * * @webref input:time_date @@ -2329,7 +2416,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from year.xml ) * - * Processing communicates with the clock on your computer. The + * Processing communicates with the clock on your computer. The year() function returns the current year as an integer (2003, 2004, 2005, etc). + * * ( end auto-generated ) * The year() function returns the current year as an integer (2003, 2004, 2005, etc). * @@ -2354,7 +2442,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from frameRate.xml ) * - * Specifies the number of frames to be displayed every second. If the processor is not fast enough to maintain the specified rate, it will not be achieved. For example, the function call + * Specifies the number of frames to be displayed every second. If the processor is not fast enough to maintain the specified rate, it will not be achieved. For example, the function call frameRate(30) will attempt to refresh 30 times a second. It is recommended to set the frame rate within setup(). The default rate is 60 frames per second. + * * ( end auto-generated ) *

Advanced

* Set a target frameRate. This will cause delay() to be called @@ -2378,7 +2467,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from param.xml ) * - * Reads the value of a param. Values are always read as a String so if you want them to be an integer or other datatype they must be converted. The + * Reads the value of a param. Values are always read as a String so if you want them to be an integer or other datatype they must be converted. The param() function will only work in a web browser. The function should be called inside setup(), otherwise the applet may not yet be initialized and connected to its parent web browser. + * * ( end auto-generated ) * * @webref input:web @@ -2400,7 +2490,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from status.xml ) * - * Displays message in the browser's status area. This is the text area in the lower left corner of the browser. The + * Displays message in the browser's status area. This is the text area in the lower left corner of the browser. The status() function will only work when the Processing program is running in a web browser. + * * ( end auto-generated ) *

Advanced

* Show status in the status bar of a web browser, or in the @@ -2434,10 +2525,10 @@ public class PApplet extends Applet * ( end auto-generated ) *

Advanced

* Link to an external page without all the muss. - *

+ *

* When run with an applet, uses the browser to open the url, * for applications, attempts to launch a browser with the url. - *

+ *

* Works on Mac OS X and Windows. For Linux, use: * 

open(new String[] { "firefox", url });
* or whatever you want as your browser, since Linux doesn't @@ -2510,7 +2601,16 @@ public class PApplet extends Applet /** * ( begin auto-generated from open.xml ) * - * Attempts to open an application or file using your platform's launcher. The + * Attempts to open an application or file using your platform's launcher. The file parameter is a String specifying the file name and location. The location parameter must be a full path name, or the name of an executable in the system's PATH. In most cases, using a full path is the best option, rather than relying on the system PATH. Be sure to make the file executable before attempting to open it (chmod +x). + *

+ * The args parameter is a String or String array which is passed to the command line. If you have multiple parameters, e.g. an application and a document, or a command with multiple switches, use the version that takes a String array, and place each individual item in a separate element. + *

+ * If args is a String (not an array), then it can only be a single file or application with no parameters. It's not the same as executing that String using a shell. For instance, open("jikes -help") will not work properly. + *

+ * This function behaves differently on each platform. On Windows, the parameters are sent to the Windows shell via "cmd /c". On Mac OS X, the "open" command is used (type "man open" in Terminal.app for documentation). On Linux, it first tries gnome-open, then kde-open, but if neither are available, it sends the command to the shell without any alterations. + *

+ * For users familiar with Java, this is not quite the same as Runtime.exec(), because the launcher command is prepended. Instead, the exec(String[]) function is a shortcut for Runtime.getRuntime.exec(String[]). + * * ( end auto-generated ) * @webref input:files * @param filename name of the file @@ -2623,7 +2723,12 @@ public class PApplet extends Applet /** * ( begin auto-generated from exit.xml ) * - * Quits/stops/exits the program. Programs without a + * Quits/stops/exits the program. Programs without a draw() function exit automatically after the last line has run, but programs with draw() run continuously until the program is manually stopped or exit() is run. + *

+ * Rather than terminating immediately, exit() will cause the sketch to exit after draw() has completed (or after setup() completes if called during the setup() method). + *

+ * For Java programmers, this is not the same as System.exit(). Further, System.exit() should not be used because closing out an application while draw() is running may cause a crash (particularly with OpenGL). + * * ( end auto-generated ) * @webref structure */ @@ -2740,7 +2845,10 @@ public class PApplet extends Applet /** * ( begin auto-generated from save.xml ) * - * Saves an image from the display window. Images are saved in TIFF, TARGA, JPEG, and PNG format depending on the extension within the + * Saves an image from the display window. Images are saved in TIFF, TARGA, JPEG, and PNG format depending on the extension within the filename parameter. For example, "image.tif" will have a TIFF image and "image.png" will save a PNG image. If no extension is included in the filename, the image will save in TIFF format and .tif will be added to the name. These files are saved to the sketch's folder, which may be opened by selecting "Show sketch folder" from the "Sketch" menu. It is not possible to use save() while running the program in a web browser. + *
+ * All images saved from the main drawing window will be opaque. To save images without a background, use createGraphics(). + * * ( end auto-generated ) * @webref output:image * @see PApplet#saveFrame() @@ -2766,7 +2874,13 @@ public class PApplet extends Applet /** * ( begin auto-generated from saveFrame.xml ) * - * Saves a numbered sequence of images, one image each time the function is run. To save an image that is identical to the display window, run the function at the end of + * Saves a numbered sequence of images, one image each time the function is run. To save an image that is identical to the display window, run the function at the end of draw() or within mouse and key events such as mousePressed() and keyPressed(). If saveFrame() is called without parameters, it will save the files as screen-0000.tif, screen-0001.tif, etc. It is possible to specify the name of the sequence with the filename parameter and make the choice of saving TIFF, TARGA, PNG, or JPEG files with the ext parameter. These image sequences can be loaded into programs such as Apple's QuickTime software and made into movies. These files are saved to the sketch's folder, which may be opened by selecting "Show sketch folder" from the "Sketch" menu. + *

+ * It is not possible to use saveXxxxx() methods inside a web browser unless the sketch is signed. To save a file back to a server, see the save to web example. + *

+ *
+ * All images saved from the main drawing window will be opaque. To save images without a background, use createGraphics(). + * * ( end auto-generated ) * @webref output:image * @see PApplet#save(String) @@ -2840,13 +2954,16 @@ public class PApplet extends Applet /** * ( begin auto-generated from cursor.xml ) * - * Sets the cursor to a predefined symbol, an image, or makes it visible if already hidden. If you are trying to set an image as the cursor, it is recommended to make the size 16x16 or 32x32 pixels. It is not possible to load an image as the cursor if you are exporting your program for the Web and not all MODES work with all Web browsers. The values for parameters + * Sets the cursor to a predefined symbol, an image, or makes it visible if already hidden. If you are trying to set an image as the cursor, it is recommended to make the size 16x16 or 32x32 pixels. It is not possible to load an image as the cursor if you are exporting your program for the Web and not all MODES work with all Web browsers. The values for parameters x and y must be less than the dimensions of the image. + *

+ * Setting or hiding the cursor generally does not work with "Present" mode (when running full-screen). + * * ( end auto-generated ) *

Advanced

* Set a custom cursor to an image with a specific hotspot. * Only works with JDK 1.2 and later. * Currently seems to be broken on Java 1.4 for Mac OS X - *

+ *

* Based on code contributed by Amit Pitaru, plus additional * code to handle Java versions via reflection by Jonathan Feinberg. * Reflection removed for release 0128 and later. @@ -3123,7 +3240,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from sqrt.xml ) * - * Calculates the square root of a number. The square root of a number is always positive, even though there may be a valid negative root. The square root + * Calculates the square root of a number. The square root of a number is always positive, even though there may be a valid negative root. The square root s of number a is such that s*s = a. It is the opposite of squaring. + * * ( end auto-generated ) * @webref math:calculation * @param a non-negative number @@ -3137,7 +3255,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from log.xml ) * - * Calculates the natural logarithm (the base- + * Calculates the natural logarithm (the base-e logarithm) of a number. This function expects the values greater than 0.0. + * * ( end auto-generated ) * @webref math:calculation * @param a int or float greater than 0.0 @@ -3149,7 +3268,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from exp.xml ) * - * Returns Euler's number + * Returns Euler's number e (2.71828...) raised to the power of the value parameter. + * * ( end auto-generated ) * @webref math:calculation * @param a the exponent to raise @@ -3161,7 +3281,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from pow.xml ) * - * Facilitates exponential expressions. The + * Facilitates exponential expressions. The pow() function is an efficient way of multiplying numbers by themselves (or their reciprocal) in large quantities. For example, pow(3, 5) is equivalent to the expression 3*3*3*3*3 and pow(3, -5) is equivalent to 1 / 3*3*3*3*3. + * * ( end auto-generated ) * @webref math:calculation * @param a base of the exponential expression @@ -3383,7 +3504,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from sin.xml ) * - * Calculates the sine of an angle. This function expects the values of the + * Calculates the sine of an angle. This function expects the values of the angle parameter to be provided in radians (values from 0 to 6.28). Values are returned in the range -1 to 1. + * * ( end auto-generated ) * @webref math:trigonometry * @param angle an angle in radians @@ -3398,7 +3520,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from cos.xml ) * - * Calculates the cosine of an angle. This function expects the values of the + * Calculates the cosine of an angle. This function expects the values of the angle parameter to be provided in radians (values from 0 to PI*2). Values are returned in the range -1 to 1. + * * ( end auto-generated ) * @webref math:trigonometry * @param angle an angle in radians @@ -3413,7 +3536,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from tan.xml ) * - * Calculates the ratio of the sine and cosine of an angle. This function expects the values of the + * Calculates the ratio of the sine and cosine of an angle. This function expects the values of the angle parameter to be provided in radians (values from 0 to PI*2). Values are returned in the range infinity to -infinity. + * * ( end auto-generated ) * @webref math:trigonometry * @param angle an angle in radians @@ -3428,7 +3552,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from asin.xml ) * - * The inverse of + * The inverse of sin(), returns the arc sine of a value. This function expects the values in the range of -1 to 1 and values are returned in the range -PI/2 to PI/2. + * * ( end auto-generated ) * @webref math:trigonometry * @param value the value whose arc sine is to be returned @@ -3443,7 +3568,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from acos.xml ) * - * The inverse of + * The inverse of cos(), returns the arc cosine of a value. This function expects the values in the range of -1 to 1 and values are returned in the range 0 to PI (3.1415927). + * * ( end auto-generated ) * @webref math:trigonometry * @param value the value whose arc cosine is to be returned @@ -3458,7 +3584,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from atan.xml ) * - * The inverse of + * The inverse of tan(), returns the arc tangent of a value. This function expects the values in the range of -Infinity to Infinity (exclusive) and values are returned in the range -PI/2 to PI/2 . + * * ( end auto-generated ) * @webref math:trigonometry * @param value -Infinity to Infinity (exclusive) @@ -3473,7 +3600,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from atan2.xml ) * - * Calculates the angle (in radians) from a specified point to the coordinate origin as measured from the positive x-axis. Values are returned as a + * Calculates the angle (in radians) from a specified point to the coordinate origin as measured from the positive x-axis. Values are returned as a float in the range from PI to -PI. The atan2() function is most often used for orienting geometry to the position of the cursor. Note: The y-coordinate of the point is the first parameter and the x-coordinate is the second due the the structure of calculating the tangent. + * * ( end auto-generated ) * @webref math:trigonometry * @param a y-coordinate of the point @@ -3487,6 +3615,7 @@ public class PApplet extends Applet /** * ( begin auto-generated from degrees.xml ) * + * Converts a radian measurement to its corresponding value in degrees. Radians and degrees are two ways of measuring the same thing. There are 360 degrees in a circle and 2*PI radians in a circle. For example, 90° = PI/2 = 1.5707964. All trigonometric methods in Processing require their parameters to be specified in radians. * * ( end auto-generated ) * @webref math:trigonometry @@ -3500,6 +3629,7 @@ public class PApplet extends Applet /** * ( begin auto-generated from radians.xml ) * + * Converts a degree measurement to its corresponding value in radians. Radians and degrees are two ways of measuring the same thing. There are 360 degrees in a circle and 2*PI radians in a circle. For example, 90° = PI/2 = 1.5707964. All trigonometric methods in Processing require their parameters to be specified in radians. * * ( end auto-generated ) * @webref math:trigonometry @@ -3513,7 +3643,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from ceil.xml ) * - * Calculates the closest int value that is greater than or equal to the value of the parameter. For example, + * Calculates the closest int value that is greater than or equal to the value of the parameter. For example, ceil(9.03) returns the value 10. + * * ( end auto-generated ) * @webref math:calculation * @param what float @@ -3542,7 +3673,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from round.xml ) * - * Calculates the integer closest to the + * Calculates the integer closest to the value parameter. For example, round(9.2) returns the value 9. + * * ( end auto-generated ) * @webref math:calculation * @param what float @@ -3601,7 +3733,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from lerp.xml ) * - * Calculates a number between two numbers at a specific increment. The + * Calculates a number between two numbers at a specific increment. The amt parameter is the amount to interpolate between the two values where 0.0 equal to the first point, 0.1 is very near the first point, 0.5 is half-way in between, etc. The lerp function is convenient for creating motion along a straight path and for drawing dotted lines. + * * ( end auto-generated ) * @webref math:calculation * @param start first value @@ -3618,6 +3751,11 @@ public class PApplet extends Applet * ( begin auto-generated from norm.xml ) * * Normalizes a number from another range into a value between 0 and 1. + *

+ * Identical to map(value, low, high, 0, 1); + *

+ * Numbers outside the range are not clamped to 0 and 1, because + * out-of-range values are often intentional and useful. * * ( end auto-generated ) * @webref math:calculation @@ -3638,6 +3776,9 @@ public class PApplet extends Applet * the number '25' is converted from a value in the range 0..100 into * a value that ranges from the left edge (0) to the right edge (width) * of the screen. + *

+ * Numbers outside the range are not clamped to 0 and 1, because + * out-of-range values are often intentional and useful. * * ( end auto-generated ) * @webref math:calculation @@ -3699,7 +3840,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from random.xml ) * - * Generates random numbers. Each time the + * Generates random numbers. Each time the random() function is called, it returns an unexpected value within the specified range. If one parameter is passed to the function it will return a float between zero and the value of the high parameter. The function call random(5) returns values between 0 and 5 (starting at zero, up to but not including 5). If two parameters are passed, it will return a float with a value between the the parameters. The function call random(-5, 10.2) returns values starting at -5 up to (but not including) 10.2. To convert a floating-point random number to an integer, use the int() function. + * * ( end auto-generated ) * @webref math:random * @param howsmall int or float @@ -3716,7 +3858,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from randomSeed.xml ) * - * Sets the seed value for + * Sets the seed value for random(). By default, random() produces different results each time the program is run. Set the value parameter to a constant to return the same pseudo-random numbers each time the software is run. + * * ( end auto-generated ) * @webref math:random * @param what int @@ -3781,7 +3924,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from noise.xml ) * - * Returns the Perlin noise value at specified coordinates. Perlin noise is a random sequence generator producing a more natural ordered, harmonic succession of numbers compared to the standard + * Returns the Perlin noise value at specified coordinates. Perlin noise is a random sequence generator producing a more natural ordered, harmonic succession of numbers compared to the standard random() function. It was invented by Ken Perlin in the 1980s and been used since in graphical applications to produce procedural textures, natural motion, shapes, terrains etc.

The main difference to the random() function is that Perlin noise is defined in an infinite n-dimensional space where each pair of coordinates corresponds to a fixed semi-random value (fixed only for the lifespan of the program). The resulting value will always be between 0.0 and 1.0. Processing can compute 1D, 2D and 3D noise, depending on the number of coordinates given. The noise value can be animated by moving through the noise space as demonstrated in the example above. The 2nd and 3rd dimension can also be interpreted as time.

The actual noise is structured similar to an audio signal, in respect to the function's use of frequencies. Similar to the concept of harmonics in physics, perlin noise is computed over several octaves which are added together for the final result.

Another way to adjust the character of the resulting sequence is the scale of the input coordinates. As the function works within an infinite space the value of the coordinates doesn't matter as such, only the distance between successive coordinates does (eg. when using noise() within a loop). As a general rule the smaller the difference between coordinates, the smoother the resulting noise sequence will be. Steps of 0.005-0.03 work best for most applications, but this will differ depending on use. + * * ( end auto-generated ) * @webref math:random * @param x x-coordinate in noise space @@ -3876,7 +4020,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from noiseDetail.xml ) * - * Adjusts the character and level of detail produced by the Perlin noise function. Similar to harmonics in physics, noise is computed over several octaves. Lower octaves contribute more to the output signal and as such define the overal intensity of the noise, whereas higher octaves create finer grained details in the noise sequence. By default, noise is computed over 4 octaves with each octave contributing exactly half than its predecessor, starting at 50% strength for the 1st octave. This falloff amount can be changed by adding an additional function parameter. Eg. a falloff factor of 0.75 means each octave will now have 75% impact (25% less) of the previous lower octave. Any value between 0.0 and 1.0 is valid, however note that values greater than 0.5 might result in greater than 1.0 values returned by + * Adjusts the character and level of detail produced by the Perlin noise function. Similar to harmonics in physics, noise is computed over several octaves. Lower octaves contribute more to the output signal and as such define the overal intensity of the noise, whereas higher octaves create finer grained details in the noise sequence. By default, noise is computed over 4 octaves with each octave contributing exactly half than its predecessor, starting at 50% strength for the 1st octave. This falloff amount can be changed by adding an additional function parameter. Eg. a falloff factor of 0.75 means each octave will now have 75% impact (25% less) of the previous lower octave. Any value between 0.0 and 1.0 is valid, however note that values greater than 0.5 might result in greater than 1.0 values returned by noise().

By changing these parameters, the signal created by the noise() function can be adapted to fit very specific needs and characteristics. + * * ( end auto-generated ) * @webref math:random * @param lod number of octaves to be used by the noise @@ -3891,7 +4036,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from noiseSeed.xml ) * - * Sets the seed value for + * Sets the seed value for noise(). By default, noise() produces different results each time the program is run. Set the value parameter to a constant to return the same pseudo-random numbers each time the software is run. + * * ( end auto-generated ) * @webref math:random * @param what int @@ -3922,7 +4068,16 @@ public class PApplet extends Applet /** * ( begin auto-generated from loadImage.xml ) * - * Loads an image into a variable of type + * Loads an image into a variable of type PImage. Four types of images ( .gif, .jpg, .tga, .png) images may be loaded. To load correctly, images must be located in the data directory of the current sketch. In most cases, load all images in setup() to preload them at the start of the program. Loading images inside draw() will reduce the speed of a program. + *

+ * The filename parameter can also be a URL to a file found online. For security reasons, a Processing sketch found online can only download files from the same server from which it came. Getting around this restriction requires a signed applet. + *

+ * The extension parameter is used to determine the image type in cases where the image filename does not end with a proper extension. Specify the extension as the second parameter to loadImage(), as shown in the third example on this page. + *

+ * If an image is not loaded successfully, the null value is returned and an error message will be printed to the console. The error message does not halt the program, however the null value may cause a NullPointerException if your code does not check whether the value returned from loadImage() is null. + *

+ * Depending on the type of error, a PImage object may still be returned, but the width and height of the image will be set to -1. This happens if bad image data is returned or cannot be decoded properly. Sometimes this happens with image URLs that produce a 403 error or that redirect to a password prompt, because loadImage() will attempt to interpret the HTML as image data. + * * ( end auto-generated ) * @webref image:load_displaying * @param filename name of file to load, can be .gif, .jpg, .tga, or a handful of other image types depending on your platform @@ -4070,7 +4225,10 @@ public class PApplet extends Applet /** * ( begin auto-generated from requestImage.xml ) * - * This function load images on a separate thread so that your sketch does not freeze while images load during + * This function load images on a separate thread so that your sketch does not freeze while images load during setup(). While the image is loading, its width and height will be 0. If an error occurs while loading the image, its width and height will be set to -1. You'll know when the image has loaded properly because its width and height will be greater than 0. Asynchronous image loading (particularly when downloading from a server) can dramatically improve performance.
+ *
+ * The extension parameter is used to determine the image type in cases where the image filename does not end with a proper extension. Specify the extension as the second parameter to requestImage(). + * * ( end auto-generated ) * @webref image:loading_displaying * @param filename name of the file to load, can be .gif, .jpg, .tga, or a handful of other image types depending on your platform @@ -4211,7 +4369,7 @@ public class PApplet extends Applet /** * Targa image loader for RLE-compressed TGA files. - *

+ *

* Rewritten for 0115 to read/write RLE-encoded targa images. * For 0125, non-RLE encoded images are now supported, along with * images whose y-order is reversed (which is standard for TGA files). @@ -4416,7 +4574,12 @@ public class PApplet extends Applet /** * ( begin auto-generated from loadShape.xml ) * - * Loads vector shapes into a variable of type + * Loads vector shapes into a variable of type PShape. Currently, only SVG files may be loaded. To load correctly, the file must be located in the data directory of the current sketch. In most cases, loadShape() should be used inside setup() because loading shapes inside draw() will reduce the speed of a sketch. + *

+ * The filename parameter can also be a URL to a file found online. For security reasons, a Processing sketch found online can only download files from the same server from which it came. Getting around this restriction requires a signed applet. + *

+ * If a shape is not loaded successfully, the null value is returned and an error message will be printed to the console. The error message does not halt the program, however the null value may cause a NullPointerException if your code does not check whether the value returned from loadShape() is null. + * * ( end auto-generated ) * @webref shape:load_displaying * @param filename name of the file to load @@ -4530,7 +4693,14 @@ public class PApplet extends Applet /** * ( begin auto-generated from loadFont.xml ) * - * Loads a font into a variable of type + * Loads a font into a variable of type PFont. To load correctly, fonts must be located in the data directory of the current sketch. To create a font to use with Processing, select "Create Font..." from the Tools menu. This will create a font in the format Processing requires and also adds it to the current sketch's data directory. + *

+ * Like loadImage() and other methods that load data, the loadFont() function should not be used inside draw(), because it will slow down the sketch considerably, as the font will be re-loaded from the disk (or network) on each frame. + *

+ * For most renderers, Processing displays fonts using the .vlw font format, which uses images for each letter, rather than defining them through vector data. When hint(ENABLE_NATIVE_FONTS) is used with the JAVA2D renderer, the native version of a font will be used if it is installed on the user's machine. + *

+ * Using createFont() (instead of loadFont) enables vector data to be used with the JAVA2D (default) renderer setting. This can be helpful when many font sizes are needed, or when using any renderer based on JAVA2D, such as the PDF library. + * * ( end auto-generated ) * @webref typography:loading_displaying * @param filename name of the font to load @@ -4579,6 +4749,12 @@ public class PApplet extends Applet * ( begin auto-generated from createFont.xml ) * * Dynamically converts a font to the format used by Processing from either a font name that's installed on the computer, or from a .ttf or .otf file inside the sketches "data" folder. This function is an advanced feature for precise control. On most occasions you should create fonts through selecting "Create Font..." from the Tools menu. + *

+ * Use the PFont.list() method to first determine the names for the fonts recognized by the computer and are compatible with this function. Because of limitations in Java, not all fonts can be used and some might work with one operating system and not others. When sharing a sketch with other people or posting it on the web, you may need to include a .ttf or .otf version of your font in the data directory of the sketch because other people might not have the font installed on their computer. Only fonts that can legally be distributed should be included with a sketch. + *

+ * The size parameter states the font size you want to generate. The smooth parameter specifies if the font should be antialiased or not, and the charset parameter is an array of chars that specifies the characters to generate. + *

+ * This function creates a bitmapped version of a font in the same manner as the Create Font tool. It loads a font by name, and converts it to a series of images based on the size of the font. When possible, the text() function will use a native font rather than the bitmapped version created behind the scenes with createFont(). For instance, when using the default renderer setting (JAVA2D), the actual native version of the font will be employed by the sketch, improving drawing quality and performance. With the P2D, P3D, and OPENGL renderer settings, the bitmapped version will be used. While this can drastically improve speed and appearance, results are poor when exporting if the sketch does not include the .otf or .ttf file, and the requested font is not available on the machine running the sketch. * * ( end auto-generated ) * @webref typography:loading_displaying @@ -4663,7 +4839,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from selectInput.xml ) * - * Opens a platform-specific file chooser dialog to select a file for input. This function returns the full path to the selected file as a + * Opens a platform-specific file chooser dialog to select a file for input. This function returns the full path to the selected file as a String, or null if no selection. + * * ( end auto-generated ) * @webref input:files * @param prompt message you want the user to see in the file chooser @@ -4687,7 +4864,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from selectOutput.xml ) * - * Open a platform-specific file save dialog to create of select a file for output. This function returns the full path to the selected file as a + * Open a platform-specific file save dialog to create of select a file for output. This function returns the full path to the selected file as a String, or null if no selection. If you select an existing file, that file will be replaced. Alternatively, you can navigate to a folder and create a new file to write to. + * * ( end auto-generated ) * @webref output:files * @param prompt message you want the user to see in the file chooser @@ -4731,7 +4909,8 @@ public class PApplet extends Applet /** * ( begin auto-generated from selectFolder.xml ) * - * Opens a platform-specific file chooser dialog to select a folder for input. This function returns the full path to the selected folder as a + * Opens a platform-specific file chooser dialog to select a folder for input. This function returns the full path to the selected folder as a String, or null if no selection. + * * ( end auto-generated ) * @webref input:files * @param prompt message you want the user to see in the file chooser @@ -4786,7 +4965,10 @@ public class PApplet extends Applet /** * ( begin auto-generated from createReader.xml ) * - * Creates a + * Creates a BufferedReader object that can be used to read files line-by-line as individual String objects. This is the complement to the createWriter() function. + *

+ * Starting with Processing release 0134, all files loaded and saved by the Processing API use UTF-8 encoding. In previous releases, the default encoding for your platform was used, which causes problems when files are moved to other platforms. + * * ( end auto-generated ) * @webref input:files * @param filename name of the file to be opened @@ -4855,7 +5037,10 @@ public class PApplet extends Applet /** * ( begin auto-generated from createWriter.xml ) * - * Creates a new file in the sketch folder, and a + * Creates a new file in the sketch folder, and a PrintWriter object to write to it. For the file to be made correctly, it should be flushed and must be closed with its flush() and close() methods (see above example). + *

+ * Starting with Processing release 0134, all files loaded and saved by the Processing API use UTF-8 encoding. In previous releases, the default encoding for your platform was used, which causes problems when files are moved to other platforms. + * * ( end auto-generated ) * @webref output:files * @param filename name of the file to be created @@ -4926,33 +5111,46 @@ public class PApplet extends Applet * ( begin auto-generated from createInput.xml ) * * This is a method for advanced programmers to open a Java InputStream. The method is useful if you want to use the facilities provided by PApplet to easily open files from the data folder or from a URL, but want an InputStream object so that you can use other Java methods to take more control of how the stream is read. + *

+ * If the requested item doesn't exist, null is returned. + *

+ * In earlier releases, this method was called openStream(). + *

+ * If not online, this will also check to see if the user is asking for a file whose name isn't properly capitalized. If capitalization is different an error will be printed to the console. This helps prevent issues that appear when a sketch is exported to the web, where case sensitivity matters, as opposed to running from inside the Processing Development Environment on Windows or Mac OS, where case sensitivity is preserved but ignored. + *

+ * The filename passed in can be:
+ * - A URL, for instance openStream("http://processing.org/");
+ * - A file in the sketch's data folder
+ * - The full path to a file to be opened locally (when running as an application) + *

+ * If the file ends with .gz, the stream will automatically be gzip decompressed. If you don't want the automatic decompression, use the related function createInputRaw(). * * ( end auto-generated ) * *

Advanced

* Simplified method to open a Java InputStream. - *

+ *

* This method is useful if you want to use the facilities provided * by PApplet to easily open things from the data folder or from a URL, * but want an InputStream object so that you can use other Java * methods to take more control of how the stream is read. - *

+ *

* If the requested item doesn't exist, null is returned. * (Prior to 0096, die() would be called, killing the applet) - *

+ *

* For 0096+, the "data" folder is exported intact with subfolders, * and openStream() properly handles subdirectories from the data folder - *

+ *

* If not online, this will also check to see if the user is asking * for a file whose name isn't properly capitalized. This helps prevent * issues when a sketch is exported to the web, where case sensitivity * matters, as opposed to Windows and the Mac OS default where * case sensitivity is preserved but ignored. - *

+ *

* It is strongly recommended that libraries use this method to open * data files, so that the loading sequence is handled in the same way * as functions like loadBytes(), loadImage(), etc. - *

+ *

* The filename passed in can be: *