Merge pull request #7902 from perminder-17/code-docs

Adding docs for `code` in the refrence.

Author: perminder-17

src/events/keyboard.js

@@ -111,7 +111,6 @@ function keyboard(p5, fn){
    */
 
   fn.keyIsPressed = false;
-  fn.code = null;
 
   /**
    * A `String` system variable that contains the value of the last key typed.
@@ -195,6 +194,191 @@ function keyboard(p5, fn){
    */
   fn.key = '';
 
+  /**
+   * The `code` property represents a physical key on the keyboard (as opposed 
+   * to the character generated by pressing the key). In other words, this 
+   * property returns a value that isn't altered by keyboard layout or the state 
+   * of the modifier keys.
+   * 
+   * This property is useful when you want to handle keys based on their 
+   * physical positions on the input device rather than the characters associated 
+   * with those keys;
+   *
+   * Unlike <a href="#/p5/key">key</a>, the `code` property differentiates between 
+   * physical keys that generate the same character—for example, `CtrlLeft` and 
+   * `CtrlRight`—so each can be handled independently.
+   * Here's the MDN docs for <a href="https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code" target="_blank">KeyboardEvent.code</a>
+
+   * 
+   * Pressing the key physically labeled “A” always yields `KeyA`, regardless 
+   * of the current keyboard layout (QWERTY, Dvorak, AZERTY, etc.) or the character 
+   * that appears in a text field.
+   * 
+   * The code property returns a plain string (e.g., 'ArrowRight'). You can 
+   * compare it directly with string literals:
+   * ```js
+   * if (keyIsDown(RIGHT_ARROW)) {
+   *   // …
+   * }
+   * // The line above is equivalent to:
+   * if (code === 'ArrowRight') {
+   *   // …
+   * }
+   * if (key  === 'ArrowRight') { 
+   * // …
+   * }
+   * ```
+   * 
+   * The system variables `BACKSPACE`, `DELETE`, `ENTER`, `RETURN`, `TAB`,
+   * `ESCAPE`, `SHIFT`, `CONTROL`, `OPTION`, `ALT`, `UP_ARROW`, `DOWN_ARROW`,
+   * `LEFT_ARROW`, and `RIGHT_ARROW` are all helpful shorthands the key codes of
+   * special keys.
+   * These are simply shorthands for the same string values:
+   * ```js
+   * if (code === RIGHT_ARROW) {
+   * // ..
+   * }
+   * ```
+   * 
+   *
+   * <p>The table below summarizes how the main keyboard-related system variables changed between p5.js 1.x and 2.x.</p>
+   * <table>
+   *   <thead>
+   *     <tr>
+   *       <th>Variable</th>
+   *       <th>p5.js 1.x </th>
+   *       <th>p5.js 2.x </th>
+   *     </tr>
+   *   </thead>
+   *   <tbody>
+   *     <tr>
+   *       <td><code>key</code></td>
+   *       <td>Text string (e.g., <code>"ArrowUp"</code>).</td>
+   *       <td>Text string (e.g., <code>"ArrowUp"</code>, <code>"f"</code> or <code>"F"</code>).</td>
+   *     </tr>
+   *     <tr>
+   *       <td><code>code</code></td>
+   *       <td><em>Not supported.</em></td>
+   *       <td>Text String (e.g., <code>"ArrowUp"</code>, <code>"KeyF"</code>).</td>
+   *     </tr>
+   *     <tr>
+   *       <td><code>keyCode</code></td>
+   *       <td>Number (e.g., <code>70</code>).</td>
+   *       <td>Number (unchanged; e.g., <code>70</code>).</td>
+   *     </tr>
+   *     <tr>
+   *       <td>System variables (<code>BACKSPACE</code>, <code>UP_ARROW</code>, …)</td>
+   *       <td>Number</td>
+   *       <td>Text String (e.g., <code>"ArrowUp"</code>).</td>
+   *     </tr>
+   *   </tbody>
+   * </table>
+   *
+   *
+   * @property {String} code
+   * @readOnly
+   *
+   * @example
+   * <div>
+   * <code>
+   * // Click on the canvas to begin detecting key presses.
+   *
+   * function setup() {
+   *   createCanvas(100, 100);
+   *
+   *   describe(
+   *     'A gray square. The last key pressed is displayed at the center.'
+   *   );
+   * }
+   *
+   * function draw() {
+   *   background(200);
+   *
+   *   // Style the text.
+   *   textAlign(CENTER);
+   *   textSize(16);
+   *
+   *   // Display the last key pressed.
+   *   text(code, 50, 50);
+   * }
+   * </code>
+   * </div>
+   * <div>
+   * <code>
+   * 
+   * function setup() {
+   *   createCanvas(100, 100);
+   * }
+   *
+   * function draw() {
+   *   background(220);
+   *   fill("black");
+   *   if (keyIsDown(BACKSPACE) || keyIsDown(ENTER) ||
+   *       keyIsDown(DELETE) || keyIsDown(RETURN) ||
+   *       keyIsDown(TAB) || keyIsDown(ESCAPE) ||
+   *       keyIsDown(CONTROL) || keyIsDown(OPTION) ||
+   *       keyIsDown(UP_ARROW) || keyIsDown(LEFT_ARROW) ||
+   *       keyIsDown(RIGHT_ARROW) || keyIsDown(DOWN_ARROW) ||
+   *       keyIsDown(SHIFT)) {
+   *     fill("red");
+   *     text("System Variable", 7, 75);
+   *   }
+   *
+   *   text(key, 30, 25);
+   *   text(keyCode, 7, 25);
+   *   text(code || " ", 30, 50);
+   * }
+   * </div>
+   * </code>
+   * <div>
+   * <code>
+   * // Click on the canvas to begin detecting key presses.
+   *
+   * let x = 50;
+   * let y = 50;
+   *  
+   * function setup() {
+   *   createCanvas(100, 100);
+   *  
+   *   background(200);
+   *  
+   *   describe(
+   *     'A gray square with a black circle at its center. The circle moves when the user presses an arrow key. It leaves a trail as it moves.'
+   *   );
+   * }
+   *  
+   * function draw() {
+   *   // Update x and y if an arrow key is pressed.
+   *   if (keyIsPressed){
+   *     if (keyIsDown(LEFT_ARROW)){
+   *       x -= 1;
+   *     }
+   *  
+   *     if (keyIsDown(RIGHT_ARROW)) {
+   *       x += 1;
+   *     }
+   *  
+   *     if (keyIsDown(UP_ARROW)) {
+   *       y -= 1;
+   *     }
+   *  
+   *     if (keyIsDown(DOWN_ARROW)) {
+   *       y += 1;
+   *     }
+   *   }
+   *  
+   *   // Style the circle.
+   *   fill(0);
+   *  
+   *   // Draw the circle.
+   *   circle(x, y, 5);
+   * }
+   *
+   * </code>
+   * </div>
+   */
+  fn.code = '';
+
   /**
    * A `Number` system variable that contains the code of the last key pressed.
    *
@@ -652,7 +836,7 @@ function keyboard(p5, fn){
     if (!this._areDownKeys()) {
       this.keyIsPressed = false;
       this.key = '';
-      this.code = null;
+      this.code = '';
     } else {
       // If other keys are still pressed, update code to the last pressed key
       const lastPressedCode = Object.keys(this._downKeyCodes).pop();