Mini ZScript Tutorial: 'ZButtons'
While you’re getting bored reading this, check out these links:
Davey's Code Reference
About IButtons, by Davey
Important commands for this tutorial:
About ZScript Buttons:
If you have read Davey’s ZScript tutorial on IButtons, you will be aware that an IButton creates a small red button in the Tutorial Window, which, when clicked, can perform instructions. It includes options for hotkeys and other helpful tools. In addition to all this, the IButton is very easy to use. It is a designed part of the language. However, suppose you want to make a button, not in the Tutorial Window, but in the Canvas area. Enter the ZButton.
Before anything else, you should know that the ZButton doesn’t really exist. Fortunately for us, the ZScript command language provides us with all the tools to make a 'ZButton', whether such a thing “really” exists or not. So what does a ZButton do? It acts like a regular button. It is an area on the screen that, when the mouse is inside, performs an action. To let the user know a button is there, it usually has a visual element to it. This often explains the button’s purpose, by saying things like “OK” or “Cancel” on it. One thing about the part where the button performs an action: There are actually two places where this can occur. The first is when the mouse is just on top of the button. This “rollover” event is often used to change the appearance of the button, a good secondary visual indicator that this is indeed a button, and that clicking it will do something. The second event happens when you click on the button. This is usually the part where the button does the big thing it supposed to do. By the way, in the current version of ZBrush, there are no separate commands for a mouse click down and a mouse click up. There is also no support for second or third buttons, or a scroll wheel. And finally, one more note. Unless you are prepared to do insane amounts of work to more carefully define it, plan on the button being a rectangle in shape. Or at least the area that will activate the button will be rectangular; the button itself need not look rectangular.
Making the ZButton:
Creating the graphic:
- The first thing to do for the button is make a graphic for it. If you want the area that activates the button to be exactly the same size and shape of the button, make this graphic a rectangle. Otherwise, do whatever you want. Save this graphic as a PSD.
- Place the graphic on the screen. An easy way is to load the graphic into the Texture Palette, then put them on a Plane3D. Use the Transform Palette to position, resize, and rotate it as necessary.
- Note: If you want, the button graphic can be made using ZScript commands so there is not separate file.
Defining the area that will activate the button:
- This is a simple trick that makes use of the [MouseHPos] and [MouseVPos] commands. These output the current location of the mouse. You will use them inside the [If...] and [Loop...] commands.
- Start with the following code:
If you are familiar with ZScript, you’ll realize this line doesn’t work yet. So continue on and complete it:
- Open the Transform Palette, and its Info sub palette. Make sure you are in Draw Pointer mode. Notice that the first two Sliders show the X and Y coordinates of the mouse. Move the mouse to the left edge of the graphic you created. Remember the first number. Now move the mouse to the right edge, and look at that number. Repeat for the bottom and top edges. Now fill in the code line with these numbers:
The actual line might look like this:
Make the button do something when the mouse is over it:
- The line of code above still doesn’t do anything. You need to decide what you want it to do. This can be just about anything, and all you need to do is add the code to the inside of the command after the last comma, like this:
You might do something like this:
This would draw a little square on the screen.
Adding a mouse click event:
- And now we finally get to the part where the button performs the important actions. The, again, can be a lot of things. First we need to let the button know it need to look for a mouse click. This will be done with the [MouseLButton] command. Insert it into our code like this:
- Simply insert the actions you want done. For example:
Making it work:
- You may realize that for this to work, it will need to be contained in a trigger command, and it needs to happened over and over and over again. The first part is easy: To trigger this whole process, put it in an IButton. Or a Routine, a Section, a Slider, or any other top level commands that will let you do things.
- The second part needs the [Loop…] command. This loops a certain number of times, repeating actions over and over again. Use this code:
If necessary, you can add more [Loop…] commands inside of the first one to make it last longer.
And now, guess what, you have a ZButton! Happy with it? I didn’t think so. So to cheer you up a bit, here is a method that is very similar, but adds a few things. Both methods have a time and place for their use.
The next method:
- This method is very similar to the last one. The difference is that whereas before we used where the mouse was in a 2D world, now we will use the fact that ZBrush is a 3D one to define the button shape. This will also take away the rectangle shape constraint.
- This is done using the [PixolPick…] command. This command helps you find out what is beneath the mouse on the canvas. And one thing it tells you is depth. Here is the code for the [PixolPick...]:
Which says, “Look where the mouse is, and tell me the ZDepth.”
- To let it know where the mouse is, we need to define to variables for the purpose.
- To make use of this, you just need to make areas of different ZDepths. For example, you might have a Circle3D object at -4 Z. You might then have the following code:
This code is the same as the code in Method One, only with the [PixolPick...] command used.
For a real demonstration of both techniques, here is a ZScript: Example Every line has a comment next to it explaining what it does, so take a look at the code.
I hope this is a useful tutorial for you, any questions, ask!