How to add custom categories and blocks.

Advanced GP Tips and Techniques

Moderator: MSandro

Post Reply
MSandro
Posts: 158
Joined: Jul 26th, '17, 21:12

How to add custom categories and blocks.

Post by MSandro » May 22nd, '18, 12:28

Hi, in this tutorial, I'll show you how to add blocks to a new custom category. I'm not talking about the "My Blocks (BYOB)" functionality. I want to show here how to create a category in GP code, how to display blocks in a category, and how to give the blocks a specific color.

You only need two classes to complete this tutorial:
Scripter.gp - Here the categories are defined
AuthoringSpecs.gp - Here the blocks are assigned and designed.

Table of Content:
1. Add a new category
2. Add blocks to your category
3. Define a color for the blocks


1. Add a new category
Before you start thinking about the blocks, you should consider whether your category should appear in Developer or User mode.

> At first you have to open the Scripter.gp file.
> If you want to add your category to DevMode, search for “method devModeCategories” otherwise search for “method userModeCategories”. Both are simple methods that return an array of category names. Add your category to the list of your choice. As this list is sorted, the categories also appear in GP. You have the choice at which point you would like to add the category.
Here is a example:

Code: Select all

method devModeCategories Scripter {
  return (array 'Control' 'Motion' 'Looks' 'Drawing' 'Drawing - Paths' 'Color' 'Pixels' 'Sensing' 'Pen' 'Sound' 'Music' 'Operators' 'Variables' 'Words' 'Data' 'Table' 'Structure' 'Network' 'Functions' 'Serial Port' 'File Stream' ‘MSandro’ 'Debugging' 'My Blocks')
}
You see, I’ve added a new category named “MSandro” between “File Stream” and “Debugging”. If you want to hide a category, simply remove it from the list.
That's it for the first part. Now you can start GP and you should see your new category in the appropriate mode.
category.png

2. Add blocks to your category
Wow, now you have your own category, but there is nothing in it. That’s why we need to add some Blocks to it. For that, we need the “AuthoringSpecs.gp” class. Open it and search for “method initialSpecs”. This method returns a array with all categories and their blocks. It’s a array with a lot of arrays in it.

> Scroll down to the end of this big array. The last block should be ‘Obsolete’. Copy it and paste it under the block. Now rename ‘Obsolete’ to the name of your category. This should now look like this:

Code: Select all

	...
	'Obsolete'
	  (array 'r' 'self_touchingMouse'	'touching mouse?')
	  (array ' ' 'self_setAlpha'		'set alpha _' 'num' 0.5)

	'MSandro'
	  (array 'r' 'self_touchingMouse'	'touching mouse?')
	  (array ' ' 'self_setAlpha'		'set alpha _' 'num' 0.5)
  )
}
If you want you can now start GP. You should see two blocks in your category. Don’t wonder about the color. I’ll explain that in chapter 3.

> Now I'll gonna explain how blocks are defined in those sub-arrays.
° The first attribute defines the type of the block. There are only 3 types:
‘ ‘ - defines a normal block
‘r’ - defines a reporter block
‘h’ - defines a header block
° The second attribute defines the method which you want to call with the block.
° The next defines the text layout of the block. Underlines symbolize a variable. You can also create expandable blocks. Whit : you can separate block parts. With ": ..." you can repeat the last part infinitely often.
° The next attribute defines the variable types. You can specify any types of objects (strings: str, numbers: num, boolean: bool, …). There are also some special types that could be interesting:
auto – can be a string or number
cmd – are used for e.g. the forever block
° With the last attribute you can define default values for your input variables. This is optional.

> Now you know how blocks are defined in this list. So let’s start adding yours. I’ll give you some examples here:

Code: Select all

(array 'r' 'dictionary'		'dictionary')
This adds a simple reporter that outputs a new dictionary.

Code: Select all

(array ' ' 'atNewIndexPut'		'add to _ at index _ key _ value _' 'dict auto auto auto')
This adds a normal block with 4 attributes. The first is defined as a dictionary, the others are auto values. I think the default block palette is big enough, so you should be able to find a block which fits your needs. Copy and modify it as you want.
blocks.png

3. Define a color for the blocks
At least, you may want to set a color for your blocks in your custom category. This is very simple. In the AuthoringSpecs.gp search for “method blockColorForCategory”. Now copy the ‘Obsolete’ part and paste it under it. Change the ‘Obsolete’ in your part to the name of your category. At (color . . .) you can define the color for your blocks.

Code: Select all

  ...
  } ('MSandro' == cat) {
	return (color 0 200 200)
  }
  ...
color.png

I hope this tutorial was helpful. I am happy to answer any question about this topic.
Thank you for reading.

User avatar
Calloway
Posts: 87
Joined: Apr 30th, '18, 00:28
Location: Eastern United States

Re: How to add custom categories and blocks.

Post by Calloway » May 22nd, '18, 19:02

Do you think this should this be pinned?
Also could John or whoever runs the admin account make a separate forum category for modding GP or just an advanced topics?

MSandro
Posts: 158
Joined: Jul 26th, '17, 21:12

Re: How to add custom categories and blocks.

Post by MSandro » May 22nd, '18, 19:49

Why not.
There is already a group called "Advanced".

Post Reply