Scripting tutorial #1 - Configuring toolbar buttons

This is a tutorial for people interested in learning more about scripting in RealWorld apps. It shouws how to add new buttons into a toolbar and how the scripting objects interact with the application.

Narration transcript

Welcome to the first episode of "Scripting in RealWorld Paint". Today, I will talk about the place of scripting in the grand scheme of things.

If you are interested in scripting, you have most likely already seen the sample script and maybe did some changes to it. You know that there are the Configuration, Execution and Preview tabs. The script in the Configuration tab allows creating user interface for scripts and add various controls to the configuration window.

The Execution script has access to the values entered by the user and contains the actual operation applied to the image. Some of the bold blue words are global objects specific to RealWorld scripting
and they allow you to work with the internal elements of RealWorld Paint. Most important is the Document object.

The Preview tab allows you to customize the preview window - you can pick an icon, a window caption, a help text and eventually a preview window. Here you can see the preview in action.

Now, let's dig deeper. Right-click on the toolbar with the custom operation and select "Configure toolbar" from the context menu. A frightening window appears. This window contains the whole configuration for this toolbar and works in a hierarchical manner.

At the top level is the "Document - Condition" object. This item makes the commands visible only if the currently selected layer is a raster image. That means that for vector images, the buttons are not visible.

Inside this item, is another item, namely the "Raster Image - Work with Selection" item. That one takes care of image masks or floating selection. Inside it is a list of commands. Clicking on the blue text takes us inside this component. You can see the hierarchical structure near the left side of the window.

So, right now, we are inside the "Command List" item. We can see its components, there are 4 document operations, a separator and then another document operation. This matches the buttons on the toolbar.

Select the last item in the list - this is the JavaScript operation. Here we can modify the the icon and the name of the button.

The next nested item is called "Document - Extract Document Part". This one makes it easy to work with the selected layer or layers. Inside it is an item called "Display Configuration". It does just that - it displays a configuration window when the button is pressed. Click the blue text again to get in.

Here we can finally see the JavaScript operation - its configuration is what the "Display Configuration" item shows. Here, we can also setup the window caption and help message.

Return to the previous screen be clicking the highlighted line in the left window. Duplicate the last button by clicking the "Duplicate" button above the list of items.

I will now copy the configuration subtree under the "Display Configuration" item. Then I will replace the "Document - Extract Document Part" with "Display Configuration" and copy its content back.

After clicking OK, there will be 1 new button in the toolbar. Try clicking on it. Surprisingly, it works the same as the old button. But this is just a coincidence. It only works because our image only has a single layer and it is not really a layered image. Look what happens when I add another layer. The old button works fine and affects the selected layer while the new button reports an error.

The problem with the new button is in the Document.RasterImage part. This time, the Document is really a layered image and we must respect that.

This is how you can access the layers in a layered image.

The layer0 variable holds the topmost layer. I will use it in the script instead of Document. This will allow me to modify the topmost layer ignoring the current selection.

This new button without the "Document - Extract Document Part" step is slightly harder to use, because it is necessary to deal with layers manually, but on the other hand, you are free to add or delete layers, modify layer styles, names, etc.

You can find more documentation online - just use the search box in the upper right corner of the page and if you are unable to find what you need, just use the Forum section to ask your question, which I would gladly answer.

Thanks for watching.

Recent comments

Anonymous

Signed comments carry more weight! Don't be a stranger - log-in or register. It only takes few seconds.