lartu/p5.clickable

Event driven, easy-to-use button library for P5.js 👆

Welcome! This is p5.clickable, a p5.js library that lets you create and customize buttons and assign event-based behaviours to them. With p5.clickable you can create buttons and define what happens when the user hovers over, clicks, releases or moves the cursor outside of them.

Can't wait? Check this live example to see some of the things this library can do. Its source code is available in the example folder of this repository.

⚠️ Attention Contributors! It seems that in one poorly checked pull request some of the newly contributes features were deleted. Sorry! I will add them again in the next release alongside all new features.

🔭 Code Example

With p5.clickable you can get a button up and running with just a few lines of code. For example, to create a plain white button at (20, 20) that when pressed changes color and shows an alert message you do:

myButton = new Clickable();     //Create button
myButton.locate(20, 20);        //Position Button
myButton.onPress = function(){  //When myButton is pressed
  this.color = "#AAAAFF";       //Change button color
  alert("Yay!");                //Show an alert message
}

Easy as pie!

🔬 Documentation

Including the p5.clickable Library

To include the p5.clickable library into your p5.js project, copy the p5.clickable.js file into your project directory and then add the line

<script src="path/to/p5.clickable.js"></script>

to the HTML file that includes your p5.js script after the line that imports the p5 library, but before all of your personal code or the line that imports your personal code. Check the example project HTML file for more information.

Creating a Clickable

p5.clickable provides the Clickable class (a Clickable is just a button). To create a button just instantiate a new Clickable, like this:

myButton = new Clickable();

The starting position of a Clickable defaults to (0, 0) and its size to (100, 50).

You can also create it at a different location:

⚠️ Sorry, this isn't working at the moment. It will be re-added in the next release.

myButton = new Clickable(200,300);

Displaying a Clickable

To display a Clickable, you have to call its draw method inside the draw function of your p5.js script.

function draw(){ // This is the p5.js draw function.
  //...
  myButton.draw(); // <- Draw the 'myButton' Clickable
  //...
}

This is very important! If you don't call this method your button will not be shown and it also won't respond to any events!

Moving a Clickable

To move a Clickable you can change its x and y properties. You can also use this properties to read the current location of a Clickable.

myButton.x = 100;
myButton.y = 200;

You can also use the locate method to change the location of a Clickable.

myButton.locate(100, 200);

Resizing a Clickable

To resize a Clickable you can modify its width and height properties. You can also use this properties to read the current size of a Clickable.

myButton.width = 250;
myButton.height = 100;

You can also use the resize method to change the size of a Clickable.

myButton.resize(250, 100);

Altering the Appearance of a Clickable

Clickables contain properties that can be changed to alter their appearance:

myButton.color = "#FFFFFF";       //Background color of the clickable (hex number as a string)
myButton.cornerRadius = 10;       //Corner radius of the clickable (float)
myButton.strokeWeight = 2;        //Stroke width of the clickable (float)
myButton.stroke = "#000000";      //Border color of the clickable (hex number as a string)
myButton.text = "Press Me";       //Text of the clickable (string)
myButton.textColor = "#000000";   //Color of the text (hex number as a string)
myButton.textSize = 12;           //Size of the text (integer)
myButton.textFont = "sans-serif"; //Font of the text (string)
myButton.textScaled = false;       //Whether to scale the text with the clickable (boolean)

Clickable Events

The Clickable class provide four methods that are called when the user interacts with a Clickable: onOutside, onHover, onPress and onRelease.

onOutside is called whenever the cursor is not hovering over the Clickable.

myButton.onOutside = function(){
  console.log("Hey! Press me!");
}

onHover is called whenever the cursor is hovering over a Clickable, but it is not being pressed.

myButton.onHover = function(){
  console.log("The cursor is over me!");
}

onPress is called when the user presses the Clickable.

myButton.onPress = function(){
  console.log("I have been pressed!");
}

onRelease is called when the user clicks a Clickable and then releases the click while within the area of the Clickable.

myButton.onRelease = function(){
  console.log("I have been released!");
}

Images in a Clickable

You can add an image to a clickable like this:

myButton.image = myImage; // myImage is an image loaded from p5's loadImage()

By default the image will stretch to fill the button, but you can disable the stretching with the fitImage property.

myButton.fitImage = true; // fits the image inside the button with the image's original aspect ratio

You can also scale the image with the imageScale property.

myButton.imageScale = 1.2; // useful if your image has some extra transparent padding

🍻 Contributing

If there's a missing feature you'd like to see on p5.clickable, feel free to write it and submit a pull request. Something broke? Please try to fix it! Also feel free to submit issues, bug reports and requests for future features.

📜 Licensing

The p5.clickable library is licensed under the MIT License. You can find a copy of the MIT License on this repository.

This repository also includes code from the p5.js library, that is licensed under the LGPL 2.1 license.

p5.clickable's Issues

Publish to NPM registry

I use npm to manage my dependencies. Could you publish this package to the npm registry? It would make it a lot more streamlined to retrieve / update / manage your library for me and a large portion of JS devs.

p5.js browser version

not sure if anyone else has this issue, but I can't get it to run on the browser version of p5. it gives me an error that Clickable() is not defined

Changing rectMode

In my code I'm using rectMode(CENTER) to make playing the buttons on the screen a bit easier. This works for displaying the Clickable however the area for the onPress function still remains where it would be if I hadn't changed the rectMode. I'm new to coding so there may be a simple fix to this that I'm missing

Link to another html file

Hi! I was wondering how can I implement opening another window after pressing a button?

ReferenceError: totalHeight is not defined

When button is drawn in function draw(), the button's text cannot be seen and other elements in the draw function are disabled.

Drawing Clickable resets p5 set attributes

Important Bug

1. When Clickable.draw() is run, it changes global textFont, stroke, etc all the p5 attributes functions which may have been set in setup function. Demo

Use push() and pop() in clickable draw function to not change the attributes set in setup()

2. When I use rectMode(CENTER) the button is drawn very wierdly.

Have a Clickable.rectMode property (similar to other properties) and ( this is due to 1st issue).

Other Enhancements (not necessarily in priority)

(these will increase the code)

1. have a createButton() function which will return new Clickable and push it to cl_clickables array
2. have a showing property to Clickable, and if it is true then automatically run draw() in runGUI().
3. p5.Clickable = function Clickable() {/* stuff */} (so we can write new p5.Clickable() instead of new Clickable()) (not necessary if you do 1.)
4. have inbuilt styles? (impractical maybe)

Make the librarie works in instance mode ?

Is the librarie works in instance mode ? I tried it without success.

I have the following error :

Uncaught ReferenceError: fill is not defined
    draw http://localhost/.../p5.clickable.js:117

Here a link of what instance mode looks like :
https://p5js.org/examples/instance-mode-instantiation.html

let sketch = function(p) {
  let x = 100;
  let y = 100;

  p.setup = function() {
    p.createCanvas(700, 410);
  };

  p.draw = function() {
    p.background(0);
    p.fill(255);
    p.rect(x, y, 50, 50);
  };
};

let myp5 = new p5(sketch);

Live example is 404

The link in Readme for the live example http://lartu.net/projects/p5.clickable/example.html is showing 404

add support for image buttons

what the title says

Release and Press Bug

Found a bug in the button!
If you press a button and move the mouse off the button, it doesn't call the onReleased function.

this.reset_btn = new Clickable();
this.reset_btn.text = "CLICK!";
this.reset_btn.onPress = function() {
	this.text = "Move mouse out button!";
	this.color = "#000";
	this.textColor = "#fff";
}
this.reset_btn.onRelease = function() {
	this.text = "Fixed?";
        this.color = "#fff";
	this.textColor = "#000";
}

Upload to CDN / cdnjs.com

This library should be uploaded to a CDN (Content Delivery Network) or cdnjs.com so that coders could use this library without downloading it.

[enhancement] CSS Cursor Pointer Support

cursor should change to pointer during hover

(can be also a pointerOnHover property)

Demonstration:
https://editor.p5js.org/dipam2006/sketches/X5H7oqSjB

P.S. not related to this, but #9 can be a function :-)