Modern Skin: Drawer Scripting

From Winamp Developer Wiki
Jump to: navigation, search

Creating a Modern Skin --> Intro --> Winamp 2 to Winamp 3+ --> Simple Skin Tutorial --> XML Intro --> Simple Skin Tutorial (Continued) --> Container --> Group --> Relative Positioning --> Complex Skin --> Non-Rect Player --> Layer Composition --> Alpha Channels --> Animatedlayer --> Snap Points --> Drawers --> Skin Scripting --> Drawer Scripting --> Animating a Skin --> Maki Overview --> Glossary


What is a MAKI Script?

What is MAKI? MAKI stands for Make A Killer Interface. It is the scripting language for modern Winamp skins. Scripting is used to produce the animations you see in the skin. Scripting is simple. It's easy! Anyone can do it! You'll love it.... Trust me.

So how does a MAKI script work?

MAKI scripts are event based. In other word, your functions are used to define behaviors when an event occurs. If you don't define action for that event, the default behavior will be used and the default behavior is defined by Winamp. Scripts are used to override an existing behavior. For example, when you click on the PL button, the playlist container appears. You can override that functionality so that the Media Library also appears. (However, we don't recommend you to do this)

What about elements I define in my own skins?

When you define new elements in your skin such as new buttons or sliders (elements that is not in the Default skin), essentially what you're doing is creating new objects. The behavior for that object is nothing.... nada until you specify an action in you XML or in your scripts.

The script to implement the animation you see below is short and simple. But it demonstrates the power of modern skins: with little programming, you can add functionalities to your skin or user interface. For more about MAKI, please read MAKI Overview.


File:Flash3.png


Compiling a MAKI script

File:Scripting dir.png


Here are the basic concepts that you should know before starting.


Directory hierarchy

All your scripts for your skin should be together in a subdirectory. Usually that subdirectory is called "scripts". In terms of hierarchy, that subdirectory is placed under your skin directory. In our example, "scripts" subdirectory is under the "ComplexTutorial" skin directory.


.m and .maki files

A sourcecode file is a text file that you can read and understand with a text program like Notepad or Editplus. The sourcecode file for your script has the .m extension. A compiled file is the result after being compiled by the compiler. It has been optimized (therefore unreadable for you) for the computer to run. The compiled script has the .maki extension.


Compiling a MAKI file

To compile a MAKI scripting, you must use the MAKI Compiler (mc.exe) in your Winamp directory. It is located in the same directory as your Winamp player. Chances are that it is located in "C:\Program Files\Winamp\Studio.exe" directory.

  1. Open a DOS Prompt: "Start Menu" => "Run..." => type "command"
  2. Change path to script directory for your skin. For this example, the path is "C:\Program Files\Winamp\Skins\ComplexTutorial\Scripts"
  3. Run mc.exe on your script. Because mc.exe is not located in the same directory as your script, you need to type "..\..\..\mc" in order to run it. For our example, it is "..\..\..\mc triangle.m" to compile triangle.m into triangle.maki.

You can set an environment variable to your Winamp directory so you don't have to type "..\..\..\" to access mc.exe. You can just type "mc triangle.m" instead. (To set an environment variable: Right on "My Computer" => "Advanced" tab => Environment Variables.)


File:Scripting dos.png


MAKI Script - triangle.m

The drawer animation is done through MAKI Scripting. The script is short and simple but it demonstrates the power of modern skins: with little programming, you can add functionalities to your skin or user interface. In your XML, you need to specify which MAKI script you want to use.


File:Scripting drawerxml.png


Lets break down the script:

Introduction Comments:

The first part of the script should be a brief introduction to the script. It should talk about the purpose and the functionality of the script.


File:Scripting trianglemaki1.png


#include Section:

The second part is the #include section. Use "#include" to include any file you need. If you need to call or use another function that is defined in another file, make sure you include that file in your script.


File:Scripting trianglemaki2.png


Variable Declaration Section

Any variable that you'll use in your script, declare them in this section.


File:Scripting trianglemaki3.png


System.onScriptUnloading() Section

When the script is unloaded, this part of the script will run. Typically, you do your clean up in this section. Our triangle script is simple and therefore doesn't need anything in this section.


File:Scripting trianglemaki4.png


System.onScriptLoaded() Section

When the script is first loaded, this part of the script will run. Typically, if anything you want to make happen when the script first start, you do that here. In our example, we initialized some objects and set the initial state for those objects. Just like the previous section, it is perfectly fine to leave this section empty. If you do that, nothing will happen when the script is loaded.


File:Scripting trianglemaki5.png


Your own functions

This section is where you put all your own functions that will define the behavior of your script. Make sure that any variable you use in this function is decared and their initial state has been initialized. For our example, we have two functions.

  • button_triangle.onleftbuttonup(int x,int y) function

This function responds to the event when the triangle button is pressed. The triangle buttons has two states: open or closed. Depending on the current state, its position is changed so that it is moved.

  • button_triangle.ontargetreached() function

This function responds to the event when the triangle has reached its destination. What event occurs, the state of the button is changed to its new state.


File:Scripting trianglemaki6.png