From da160d7ed6bbe62d7f3e090fbc91dd97fcdac7e3 Mon Sep 17 00:00:00 2001 From: Abdulkaiz Khatri <24286590+ful1e5@users.noreply.github.com> Date: Mon, 22 Jul 2024 15:53:09 +0530 Subject: [PATCH] docs: Updated docs according to build tools --- CONTRIBUTING.md | 52 ++++++++++++ README.md | 216 +++++++++++++++++++++++++++++++----------------- 2 files changed, 190 insertions(+), 78 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b41c4ee --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing to Banana Cursor + +I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's: + +- Becoming a maintainer +- Proposing new features +- Submitting a fix +- Discussing the current state of the code +- Reporting a bug + +## I Develop with Github + +I use github to host code, to track issues and feature requests, as well as accept pull requests. + +## I Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests + +Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests: + +1. Fork the repo and create your branch from `main`. +2. If you've added code that should be tested, add tests. +3. If you've changed Look, update the documentation. +4. Issue that pull request! + +## Any contributions you make will be under the GPL - 3.0 Software License + +In short, when you submit code changes, your submissions are understood to be under the same [GPL - 3.0 License](https://www.gnu.org/licenses/gpl-3.0.en.html) that covers the project. Feel free to contact the maintainers if that's a concern. + +## Report bugs using Github's [issues](https://github.com/ful1e5/fuchsia-cursor/issues) + +I use GitHub issues to track public bugs. Report a bug by opening a new issue, it's that easy! + +## Write bug reports with detail, background, and sample code + +**Great Bug Reports** tend to have: + +- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) +- What actually happens +- What you expected would happen + - Give sample code if you can. + - Be specific! +- Steps to reproduce +- A quick summary and/or background + +People _love_ thorough bug reports. I'm not even kidding. + +## License + +By contributing, you agree that your contributions will be licensed under its `GPL-3.0` License. + +## References + +This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md) diff --git a/README.md b/README.md index cd35a82..80ee4be 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,31 @@ # banana-cursor -The banana cursor. +A cursor was requested by [u/JMT37](https://www.reddit.com/user/JMT37/). It is the most unique cursor ever crafted in Linux history. [![build](https://github.com/ful1e5/banana-cursor/actions/workflows/build.yml/badge.svg)](https://github.com/ful1e5/banana-cursor/actions/workflows/build.yml) -## Banana Cursor needs your Input +## Notes -Until 2021 my cursors projects were well funded by [pling.com](https://www.pling.com) but since the -[pling-factor](https://www.pling.com/terms/payout) on the website has decreased and monthly payments -are <500$, It is now dependent on community funding and sponsorships. If you want to help me to maintain -Banana Cursor and my other open source projects actively, consider sponsoring my work on [GitHub Sponsor](https://github.com/sponsors/ful1e5) -or DM me on [Twitter](https://twitter.com/ful1e5) if your company would like to support my projects, -I will gladly look into it and post your avatar in the project's README. +- All cursor's SVG files are found in [svg](./svg) directory or you can also find them on [Figma](https://www.figma.com/file/rL9ngfrDJbXqNW4pUESANY/banana-cursor?node-id=0%3A1). -I appreciate all the wonderful people who patronize and sponsoring my work. + -## Sponsors +![shoutout-sponsors](https://sponsor-spotlight.vercel.app/sponsor?login=ful1e5) - - -N/A +- **2024-07-21**: [04eb3aa](https://github.com/ful1e5/banana-cursor/commit/04eb3aa80d76c3e27d2e5870de3cb57b19b69a61) Partitioned cursor build configuration into multiple files according to platform: + `build.toml` -> `configs/win_lg.build.toml`, `configs/win_rg.build.toml`, `configs/win_xl.build.toml`, `configs/x.build.toml`. --- ![Banana](https://imgur.com/pCoon2Q.png) -> **Note** -> All cursor's `.svg` files are found in [svg](./svg) directory or you can also find them on -> [Figma](https://www.figma.com/file/rL9ngfrDJbXqNW4pUESANY/banana-cursor?node-id=0%3A1). - -#### Cursor Sizes - -22 -24 -28 -32 -40 -48 -56 -64 -72 -80 -88 -96 - ## Cursor Sizes ### Xcursor Sizes: +16 +20 22 24 28 @@ -63,10 +41,20 @@ N/A ### Windows Cursor Size: -- 16x16 - Small -- 24x24 - Regular -- 32x32 - Large -- 48x48 - Extra Large +| size | Regular (× ²⁄₃) | Large (× ⁴⁄₅) | Extra-Large (× 1) | +| ---: | --------------: | ------------: | ----------------: | +| 32 | 21.333 → 22 | 25.6 → 26 | 32 | +| 48 | 32 | 38.4 → 39 | 48 | +| 64 | 42.666 → 43 | 51.2 → 52 | 64 | +| 96 | 64 | 76.8 → 77 | 96 | +| 128 | 85.333 → 86 | 102.4 → 103 | 128 | + +## Colors + +### Banana + +- Outline Color - `#6D3C1B` (Brown) +- Base Color - `#FCD900` (Yellow) ## How to get it @@ -119,72 +107,71 @@ Run the `uninstall.bat` script packed with the `.zip` archive ## Build From Source -#### Notes +### Prerequisites -- Banana build configuration and cursor hotspot settings are bundled in the `build.toml` file. -- Check out the scripts section in [package.json](./package.json) to see how we build the cursor theme, - excluding the render scripts. They are useful for converting `.svg` files to `.png` files. -- yarn is optional, For building XCursors and Windows cursors from `.png` files or resizing them - you don't need that. If you want to develop/modify Banana's colors, and bitmaps, or generate a png - file from a svg, Then you can use yarn because bitmapper is written in TypeScript. +- Python version 3.7 or higher +- [clickgen](https://github.com/ful1e5/clickgen)>=2.2.5 (`pip install clickgen`) +- [yarn](https://github.com/yarnpkg/yarn) -### Build prerequisites +### Quick start -- Python version 3.7 or higher -- [clickgen](https://github.com/ful1e5/clickgen)>=2.1.2 (`pip install clickgen`) -- [yarn](https://github.com/yarnpkg/yarn) +1. Install [build prerequisites](#prerequisites) on your system +2. `git clone https://github.com/ful1e5/banana-cursor` +3. `cd banana-cursor` +4. `yarn install` +5. `yarn generate` +6. See [Installing Banana Cursor](#installing-banana-cursor). -### Quick start +### Getting Started -1. Install [build prerequisites](#build-prerequisites) on your system -2. `https://github.com/ful1e5/banana-cursor` -3. `cd banana-cursor && yarn build` -4. See [Installing Banana Cursor](#installing-banana-cursor). - click `Delete`. -5. Click '**yes**' when prompted. +Once you have the [build prerequisites](#prerequisites) installed, You can personalize colors, +customize sizes, change target platforms, and more. This process involves using external tools, +as this repository only contains SVG files and configuration for these tools: -### Building +- [cbmp](https://github.com/ful1e5/cbmp): Used for customizing colors and generating PNG files. +- [ctgen](https://github.com/ful1e5/clickgen): Used for customizing sizes and building XCursor and Windows Cursors. -> **Note** -> Bitmaps are already generated in the `bitmaps` directory and **managed by the maintainer** -> (do not edit them directly). +You can refer to the README of each tool for more information on their command-line options. -First make sure you installed the [build prerequisites](#build-prerequisites). -Now that you have the dependencies, you can try build individual themes from bitmaps and -customize sizes, target platform, and etc. with the `ctgen` CLI (packed with `clickgen`). +#### Crafting Your Banana Cursor -#### `yarn build` aberration +The process of creating custom cursor themes involves two main steps: -Here are the default commands we used to build the Banana-cursor and packed them into `yarn build`: +1. Rendering SVG files to PNG files. +2. Building cursor themes from PNG files. + +#### Customize Colors + +`cbmp` provides three options for changing colors: + +1. `-bc`: Base color, which replaces the `#00FF00` color in the SVG. +2. `-oc`: Outlined color, which replaces the `#0000FF` color in the SVG. +3. `-wc` (optional): Watch Background color, which replaces the `#FF0000` color in the SVG. ```bash -ctgen build.toml +npx cbmp [...] -bc "" -oc "" -wc "" ``` -Afterwards, the themes can be found in the `themes` directory. +Alternatively, you can provide a JSON configuration file to render SVG files, which contains a sequence of `cbmp` commands: -#### Customize Sizes +```bash +npx cbmp render.json +``` -> **Note** -> You can change the cursor size up to 200 because pngs are rendered with 200x200. -> If the cursor is resized by more than rendered png size, the final cursor will be blurred. +#### Customize Sizes ##### Customize Windows Cursor size To build Windows cursor with size `16`: -> **Warning** -> Windows cursor supports only one size, if multiple sizes are given with `-s` the first size will -> be considered in build. - ```bash -ctgen build.toml -s 16 -p windows -c 'Banana cursors with size 16' +ctgen configs/x.build.toml -s 16 -p windows -d "bitmaps/Banana" -n "Banana" -c "The Banana XCursors with size 16" ``` You can also customize output directory with `-o` option: ```bash -ctgen build.toml -s 16 -p windows -o 'out' -c 'Banana cursors with size 16' +ctgen configs/win_xl.build.toml -s 16 -p windows -d "bitmaps/Banana" -o "out" -n "Banana" -c "The Banana Windows Cursors with size 16" ``` ##### Customize XCursor size @@ -192,19 +179,92 @@ ctgen build.toml -s 16 -p windows -o 'out' -c 'Banana cursors with size 16' To build XCursor with size `16`: ```bash -ctgen build.toml -s 16 -p x11 -c 'Banana cursors with size 16' +ctgen configs/x.build.toml -s 16 -p x11 -d "bitmaps/Banana" -n "Banana" -c "The Banana XCursors with size 16" ``` You can also assign multiple sizes to `ctgen` for XCursors build: ```bash -ctgen build.toml -s 16 24 32 -p x11 -c 'Banana cursors with size 16' +ctgen configs/x.build.toml -s 16 18 24 32 -p x11 -d "bitmaps/Banana" -n "Banana" -c "The Banana XCursors with size 16" ``` +#### Examples + +Lets generate Banana Cursor with green and black colors: + +```bash +npx cbmp -d "svg" -o "bitmaps/Banana-Hacker" -bc "#00FE00" -oc "#000000" +``` + +After rendering custom color you have to build cursor through `ctgen`: + +```bash +ctgen configs/x.build.toml -d "bitmaps/Banana-Hacker" -n "Banana-Hacker" -c "Green and Black Banana XCursors." +``` + +Afterwards, Generated theme can be found in the `themes` directory. + +###### Banana Gruvbox + +```bash +npx cbmp -d "svg" -o "bitmaps/Banana-Gruvbox" -bc "#282828" -oc "#EBDBB2" + +ctgen configs/x.build.toml -d "bitmaps/Banana-Gruvbox" -n "Banana-Gruvbox" -c "Groovy Banana XCursors." +ctgen configs/win_rg.build.toml -d "bitmaps/Banana-Gruvbox" -n "Banana-Gruvbox" -c "Groovy Banana Windows Regular Cursors." +ctgen configs/win_lg.build.toml -d "bitmaps/Banana-Gruvbox" -n "Banana-Gruvbox" -c "Groovy Banana Windows Large Cursors." +ctgen configs/win_xl.build.toml -d "bitmaps/Banana-Gruvbox" -n "Banana-Gruvbox" -c "Groovy Banana Windows Extra Large Cursors." +``` + +###### Banana Solarized Dark + +```bash +npx cbmp -d "svg" -o "bitmaps/Banana-Solarized-Dark" -bc "#002b36" -oc "#839496" + +ctgen configs/x.build.toml -d "bitmaps/Banana-Solarized-Dark" -n "Banana-Solarized-Dark" -c "Solarized Dark Banana XCursors." +ctgen configs/win_rg.build.toml -d "bitmaps/Banana-Solarized-Dark" -n "Banana-Solarized-Dark" -c "Solarized Dark Banana Windows Regular Cursors." +ctgen configs/win_lg.build.toml -d "bitmaps/Banana-Solarized-Dark" -n "Banana-Solarized-Dark" -c "Solarized Dark Banana Windows Large Cursors." +ctgen configs/win_xl.build.toml -d "bitmaps/Banana-Solarized-Dark" -n "Banana-Solarized-Dark" -c "Solarized Dark Banana Windows Extra Large Cursors." +``` + +###### Banana Solarized Light + +```bash +npx cbmp -d "svg" -o "bitmaps/Banana-Solarized-Light" -bc "#839496" -oc "#002b36" + +ctgen configs/x.build.toml -d "bitmaps/Banana-Solarized-Light" -n "Banana-Solarized-Light" -c "Solarized Light Banana XCursors." +ctgen configs/win_rg.build.toml -d "bitmaps/Banana-Solarized-Light" -n "Banana-Solarized-Light" -c "Solarized Light Banana Windows Regular Cursors." +ctgen configs/win_lg.build.toml -d "bitmaps/Banana-Solarized-Light" -n "Banana-Solarized-Light" -c "Solarized Light Banana Windows Large Cursors." +ctgen configs/win_xl.build.toml -d "bitmaps/Banana-Solarized-Light" -n "Banana-Solarized-Light" -c "Solarized Light Banana Windows Extra Large Cursors." +``` + +###### Banana Dracula + +```bash +npx cbmp -d "svg" -o "bitmaas/Banana-Dracula" -bc "#282a36" -oc "#f8f8f2" + +ctgen configs/x.build.toml -d "bitmaps/Banana-Dracula" -n "Banana-Dracula" -c "Dracula Banana XCursors." +ctgen configs/win_rg.build.toml -d "bitmaps/Banana-Dracula" -n "Banana-Dracula" -c "Dracula Banana Windows Regular Cursors." +ctgen configs/win_lg.build.toml -d "bitmaps/Banana-Dracula" -n "Banana-Dracula" -c "Dracula Banana Windows Large Cursors." +ctgen configs/win_xl.build.toml -d "bitmaps/Banana-Dracula" -n "Banana-Dracula" -c "Dracula Banana Windows Extra Large Cursors." +``` + +## Testing Cursor + +There are several websites that allow you to test your cursor states by hovering over buttons. This can be very useful when developing or verifying the behavior of a cursor. The following websites cover many of the most commonly used cursors, although they may not include all available options. + +- [Cursor-Test](https://vibhorjaiswal.github.io/Cursor-Test/) +- [Mozilla CSS Cursor](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor) + +For a blueprint for creating XCursors, you may also want to refer to [Cursor-demo](https://wiki.tcl-lang.org/page/Cursor+demo). + # Bugs Bugs should be reported [here](https://github.com/ful1e5/banana-cursor/issues) on the Github issues page. -# Getting Help +## Getting Help You can create a **issue**, I will help you. + +## Contributing + +Check [CONTRIBUTING.md](CONTRIBUTING.md), any suggestions for features and contributions to the continuing code masterelopment can be made via the issue tracker or code contributions via a `Fork` & `Pull requests`.