Making and submitting a standardized plugin or theme

This is a guide on how to create and submit a standardized plugin or theme.

Table of Contents

Making a plugin

Choosing a filename

  • First, you make your new plugin file. For this example, we’ll be using the discordrpc plugin. Make a new python file preferably named to something relevant to your plugin. We’ll be choosing the filename discordrpc.py for this.

Importing features from core

  • If you want to make use of some features from the core.py file, you can just import them. For instance, we want to import the current theme if the plugin is printing stuff and the config if the plugin is configurable, so at the top of our python file, we will put

from systemPlugins.core import config, theme

If you want to import anything else from core, you can just add it to the list of things being imported, for instance, if you wanted to import the restart() function, it would look like

from systemPlugins.core import config, theme, restart

Running code on calculator start

If you want to run some code when the calculator is started, for instance, asking the user what their name is to adjust the config, you can just put the code underneath all of your imports in the python file. Example:

from systemPlugins.core import config, theme, restart

# Get user's name
name = input("Input your name here: ")

Giving answers

When giving answers, it’s better to return an answer instead of printing it. This will allow for the resulting calculation to be used in other calculations.

Printing Information

If you are doing anything involving printing, like taking input or just using print(), you should make it display with the user’s theme’s color for that type of output. To see the current color palette, you can type dev.showPalette() in the calculator. The available styles can be found below:

  • Normal - No styling

  • Error - Error Styling

  • Warning - Warning Styling

  • Important - Important Text Styling

  • StartupMessage - Startup Message styling

  • Prompt - The color of the prompt (Default prompt is > )

  • Link - Hyperlink Style

  • Answer - The color that is used when a function returns a value

  • Input - The color used for taking input (input())

  • Output - General output color

To print something with a specific color, make sure you import theme from core, and then you can print like this:

#General output
print(theme["styles"]["output"] + "This is some pretty cool general output")

#Taking input
input(theme["styles"]["input"] + "How are you liking this cool theme stuff? ")

#Using a variable
importantVariable = "YOU BETTER PAY ATTENTION TO ME BECAUSE THIS IS VERY IMPORTANT"
print(theme["styles"]["important"] + importantVariable)

Handling special events

The calculator will send a signal to plugins when certain events happen. This can be taken advantage of by making a function in your plugin with the same name as the signal name. Some signals take arguments, so that you can do something with the data. Available signal names can be found below:

  • onRestart - Activated when the calculator restarts

  • onPluginsLoaded - Activated when all plugins have been loaded

  • onLinuxStart - Activated when the calculator is started on a Linux operating system

  • onHaikuStart - Activated when the calculator is started on Haiku

  • onWindowsStart - Activated when the calculator is started on Windows

  • onMacStart - Activated when the calculator is started on MacOS

  • onUnknownStart - Activated when the calculator is started on an unknown operating system

  • onStarted - Activated once calculator is fully started

  • onReady - Activated once calculator is ready for user input

  • onInput - Activated when user inputs something, like a calculation (passes the input as an argument)

  • onError - Activated on error (passes the exception type as an argument)

  • onPrintAnswer - Activated when the answer is printed

  • onEofExit - Activated when a user exits the calculator by pressing Ctrl + D

  • onFatalError - Activated when the calculator encountered a fatal error and cannot continue (passes the exception type as an argument)

  • onSettingsSaved - Activated when the settings have been saved and the config file has been updated

An example of the use of these signals can be found here:

#This is in your plugin file
def onLinuxStart():
   print(theme["styles"]["output"] + "Hey, you\'re pretty cool, you use linux.")

def onWindowsStart():
   print(theme["styles"]["output"] + "Ew, Windows")

#Since this passes an argument, you must add an argument in the function
def onError(err):
   if err == NameError:
   	print(theme["styles"]["error"] + "Whatever you tried to do includes an undefined variable")

Debugging your plugin

While debugging your plugin a simple error type may not be enough; you may need a traceback. To get the full traceback, you can change debug in the dev section of the config file to true. You can do this manually, with settings.editor() in the calculator, or with settings.configMod("dev", "debug", "true").

Making a theme

Users can make custom themes for iicalc. This is a guide on how to create them.

Manually making a theme

A theme file has a basic structure. You have the section that tells all of the information about the theme and the section that defines the actual colors. Themes currently support the use of colorama colors and ANSI colors. First, make a new theme file with the .iitheme extension. We’ll call ours test.iitheme. Now, open the theme file in an editor and paste this theme template into it, replacing NAME and DESCRIPTION with the values that you are using.

[theme]
name = NAME
description = DESCRIPTION
ansi = false

[styles]
normal = No
error = No
warning = No
important = No
startupmessage = No
prompt = No
link = No
answer = No
input = No
output = No

If you are using ANSI colors, change ansi to true, if not, leave it as false. Now for the fun part, the colors. You can either use ANSI colors, or if you’re going for something more basic, you can use colorama. Replace every instance of No with the corresponding color that you would like for that value. Here is a list of what every value is for. Here are 2 examples, one for colorama and one for ANSI:

Colorama:

[styles]
normal = colorama.Fore.RESET + colorama.Back.RESET + colorama.Style.NORMAL
error = colorama.Fore.RED + colorama.Back.RESET + colorama.Style.BRIGHT
warning = colorama.Fore.YELLOW + colorama.Back.RESET + colorama.Style.NORMAL
important = colorama.Fore.MAGENTA + colorama.Back.RESET + colorama.Style.BRIGHT
startupmessage = colorama.Fore.YELLOW + colorama.Back.RESET + colorama.Style.NORMAL
prompt = colorama.Fore.GREEN + colorama.Back.RESET + colorama.Style.BRIGHT
link = colorama.Fore.BLUE + colorama.Back.RESET + colorama.Style.BRIGHT
answer = colorama.Fore.GREEN + colorama.Back.RESET + colorama.Style.NORMAL
input = colorama.Fore.CYAN + colorama.Back.RESET + colorama.Style.NORMAL
output = colorama.Fore.WHITE + colorama.Back.RESET + colorama.Style.NORMAL

ANSI:

[styles]
normal = \u001b[38;5;238m\u001b[48;5;19m
error = \u001b[38;5;197m\u001b[48;5;201m
warning = \u001b[38;2;219;203;72m
important = \u001b[38;5;236m\u001b[48;5;47m
startupmessage = \u001b[38;5;21m\u001b[48;5;39m
prompt = \u001b[38;5;227m\u001b[48;5;126m
link = \u001b[38;5;26m\u001b[48;5;137m
answer = \u001b[38;5;225m\u001b[48;5;237m
input = \u001b[38;5;178m\u001b[48;5;36m
output = \u001b[38;5;143m\u001b[48;5;225m

While ANSI gives more power over the colors, colorama is simpler, so it’s up for you to decide which best fits your needs. If you’re interested in ANSI, I’ve found this article fairly useful in getting you started.

Using a tool

If you don’t want to manually make a theme, or you want to have more control by using ANSI, but just can’t understand that, there are some tools to help you in making themes. I’ve included a list below of some good ones.

  • Builtin themes.editor() command - good for making themes from a command line, no ANSI support.

  • themegui plugin. This plugin can be installed with pm.install("themegui") or through pm.store() (store.store() is now deprecated and will be removed in a future version). This plugin uses Tkinter and has adjustable RGB values with a preview. This plugin also has ANSI support.

Publishing your plugin to the store

NOTICE: THE PLUGIN STORE IS NO LONGER AVAILABLE.

Submiting a plugin

  1. Open your browser and go to https://turbowafflz.azurewebsites.net/auth. Note that this make take a minute or two depending if the server is online or not.

  2. Click on the “Submit a new plugin” button.

  3. Type: Click on the first dropdown menu and select if your plugin is a plugin or a theme.

  4. Name: Go to the name input box, and type your plugin name, preferably a name that is all lowercase.

  5. Description: Type the description of your plugin or theme in the description box, this will be displayed on the plugin page in the store.

  6. Short Description: Underneath the description box is the short description, this will be displayed in the store as a sort of preview description.

  7. Version: Now put in the plugin version, this would probably be 1.0 or 1.0.0 if its the first release version.

  8. Dependencies: Now you can add dependencies if you are submitting a plugin and not a theme. These can be other plugins, or PyPI packages in a comma separated list. PyPI packages must my prefixed with pypi:. For example, if you depended on the formulas plugin and the PyPI package numpy, you would put formulas, pypi:numpy. This can be left blank if there are no dependencies.

  9. Download link: Go to the download link box. You must use Github or Gitlab to host the files, for instance, I have a central repository for all of my plugins that you can find here. Once you’ve uploaded your plugin to Github or Gitlab, go to the file, and hit the “Raw” button on the right if on Github, or the “Open Raw” icon button on the right if on Gitlab. Now copy the current URL and paste it into the download link input. It should look something similar to https://raw.githubusercontent.com/user/repository/branch/file.py or https://gitlab.com/user/repository/-/raw/branch/file.py

  10. File name: Now, put the filename of the plugin on Github or Gitlab into the filename box.

  11. File hash: Now you must get the SHA256 hash of the file. Follow the instructions below depending on your operating system. If your OS is not listed, search how to get the SHA256 has of a file on your OS.

    • Linux: Navigate to the directory where the file is located in your terminal, and type sha256sum file.py, replacing file.py with your filename.

    • MacOS: Navigate to the directory where the file is located in your terminal, and type shasum -a 256 file.py, replacing file.py with your filename

    • Windows: Open PowerShell. Navigate to the directory where the file is located, and type Get-FileHash file.py | Format-List, replacing file.py with your filename. Now copy the value after Hash:

  12. Calculator Version: This is where you put the calculator version requirements that are needed for your plugin to run. For example, if your plugin only runs on version 1.5.6 and below, you would type <=1.5.6 in the text box. You can add multiple requirements by separating them with commas. To view more about the types of version specification you can do, look at the documentation for PEP 440

  13. Maintainers: You can add maintainers by their Github usernames. You are added automatically as a maintainer. If you do not press enter after typing a name, it will not be counted as a maintainer, though you can add or remove maintainers later on.

Updating your plugin

Once you want to update your plugin, you can go to https://turbowafflz.gitlab.io/updateplugin.html or click the “Update an existing plugin” button on the index portal. The same process applies for uploading a plugin, but with something to ease the proccess. If you type your plugin name into the name input and click the “Autofill” button, it will autofill the applicable information. Note that this make take a minute if the server went to sleep. You should increase the version number and recalculate the file hash and make and necessary changes, and then hit the submit button.

Deleting a plugin

Only the creator of a plugin can delete it. There are 2 ways to do this. The first option is to go here and select it from the list. The second option is to go to here, select your plugin, and then press the delete button on the plugin page. Note that the page’s may take a minute to load if the server went to sleep.

Reporting a plugin

If you find a plugin that violates our guidelines, you can report it by going to https://turbowafflz.azurewebsites.net/iicalc/browse, selecting the desired plugin, and pressing the report button on the plugin’s page.

Rating a plugin

There are 2 ways to rate a plugin. The first way is to go to the plugin’s page (find it at https://turbowafflz.azurewebsites.net/iicalc/browse) and hit the upvote or downvote button. You must be authenticated to do this. The 2nd way is through the calculator. Start the calculator and run pm.connect() if you haven’t done that already. Follow the steps and once you’re authenticated, you can either run pm.rate("pluginname"), or by going to the plugin’s store page, accessed with pm.store() (store.store() is now deprecated and will be removed in a future version).

Any problems?

Did you get an error or encounter something broken? Start an issue at https://gitlab.com/TurboWafflz/ImaginaryInfinity-Calculator/-/issues