How do I use the Base plugin sources ?
The base plugin is intended for those who wish to make a skinnable application that can interface directly with RR. It can however be used to make a simple Skinnable application (launched directly instead of from within RR).
The main thing you need to know is that the base plugin sources are meant to be used with Visual Basic 6 (no earlier version nor with .NET) -- although I never tried an earlier version. The instructions here won't be of much help if you can't program VB6 or if you don't have it available. In any case, VB6 is one of the easiest languages available, so if you have SOME programming experience in Basic, Delphi, VC++, Builder etc, it's likely you can probably manage to work with VB6.
So here are the basics you need to know in order to get started:
1-Copy the Base Plugin folder to a development location and rename the BASEPLUGIN.* files to the name of the plugin you're creating.. like MYPLUGIN. This is done to keep a copy of the original (always helpful) and to just keep your files organized.
2-Open the project file you created (i.e. MYPLUGIN.VBP) in VB6
3-Under the Project View Window, select the name of the project "BasePlugin" on top of the list, under the properties view window (F4 brings it up), you should see the name of the project "BasePlugin", set your plugin's name there (i.e. MyPlugin). Save the project using the file menu.
4-Under the Project view window, double click on modRRPlugin.bas. It will open the code view for that module. Read the top portion of that module (the comments -- in green). Make sure you are capable of understanding the terms of usage and what the features are possible with the plugin.
5-Under the Project view window, double click on frmCOM, click the form to select the form object then under the properties view window, set the CAPTION property to your plugin's name (i.e. MyPlugin).
6-Set the INITIALSKIN constant to the name of the .skin file you wish to load as the main screen of your plugin. (i.e. myplugin.skin). By default, the skin files should be under a SKIN sub-folder of the plugin's folder. (i.e. C:\MyPlugin\Skin\)
Those steps above will get you setup to load skins with unlimited buttons, labels and indicators. Those will work in the same manner as the would in RR -- read skin commands.txt and the skinning tutorials if you need to get familiar with skin objects.
To make those buttons, labels and indicators (that you defined in your skin) work, all you have to do is create the code that is executed when pressing the buttons and the code that sets the labels' text and the indicator statuses. The use of each of those objects is optional.
-The base plugin is basically a stripped out version of an early Release of RoadRunner iteself. As such, it incorporates many of the principles used in RR to provide multiple screens and skin support. Many of those feautes are somewhat obsolete and/or out-of-date when compared to the lates RR releases. But mainly what you need to know is that due to the dynamic objects nature of this project, you SHOULD NEVER reference frmSkin directly (i.e. frmSkin.lbl(0) etc). Instead, you should always reference the dynamic array MENUS containing the screens of your plugin (ie. Menus(0) has your first/main screen, menus(1) your secondary screen/menu etc). You can verify the name of the loaded screen using the IsLoaded() function. For instance: IsLoaded("myplugin.skin") should have the number of the myplugin screen in memory, thus Menus(IsLoaded("myplugin.skin")).lbl(0) should effectively replace a desired frmSkin.lbl(0) reference that should not be used.
-If you wish to keep your code organized, it is higly recommended that you use variables and procedures to keep the code of the main functions clean (LabelInfo, Exec, UpdateIndicators etc). Using variables that update on a separate timer event (that you can add), would most definitely improve the time it takes to update the screen.
-In order to load the plugin from RR, you should use the same PLUGIN command used on the CDRip plugin. This command REQUIRES that a valid wait.skin file is available at the CURRENT skin's folder. Alternatively it is possible to add a REQUEST command at your plugin's startup procedure, so that it loads a respective .skin file from RR's current skin (instead of the SKIN\ subfolder of the plugin) -- this is not done by default.
Creating a new BUTTON code
This is how you'd create a new button code to be used from your .skin file.
Say for instance you'd like to create a command called "MYCOMMAND" to be used in your .skin file. All you have to do is:
-Locate the Exec() function under modRRPlugin.
-Locate the section that says "Commands not used for navigation". You should see two example commands in there called "mycommand1" and "mycommand2". You can rename/remove add new button commands in the same fashion. In our case, we'd remove the '1' from the first command (leaving it "mycommand") then simply add the code/function calls to be executed when that button is pressed under the case "mycommand" line.
That's it!, when you press your button on your skin, whatever you placed on that space of the code will be executed! Best of all, if your plugin has multiple screens, that new command will work from ANY screen. Also, if you have added "MYCOMMAND" in the list of commands that can have a "repeat" function, you can check the variable "asrepeat" to know if the button was simply clicked or if it is being executed as result of a press-and-hold.
You can add as many case statements as desired to create as many button codes as you need. Unused button codes do NOT slow down or interfere in any way with other button codes used. Any standard RR buttom code that you do not re-define, will be sent to RR to be processed as a normal command, this allows you to use RR's commands within your plugin's skin (PLAY/PAUSE etc).
NOTE: it is important that your command be listed all in lowercase for it to be propperly processed. This is regardless of how you typed the command in the .skin file.
Creating a new LABEL code
Say for instance you'd like to create a command called "MYLABELCODE" to be used in your .skin file. All you have to do is:
-Locate the LabelInfo() function in modRRPlugin
-Locate the case statement under "Process Tag Code". You should see the example "MYLABELCODE" created. All you have to do is ADD to the variable "s" the contents that this label code is supposed to display.
Say that your "MYLABELCODE" code is supposed to display my name (Guino), all you'd have to do is add this under the case statement:
s = s + "Guino"
That's it! Your label code will also work with the common >> and || tags used from RR and will work from any screen on your plugin! You can also place there (under that case statement of your label code) any code that you'd wish to execute in order to obtain/generate the text to be displayed. You should only be careful to notice that that code will be executed roughly once-every-second, and if any code in there takes longer to execute, it will likely create a LAG on your plugin making it act "sluggish" or "slow".
You can add as many case statements as desired to create as many label codes as you need. Unused label codes do NOT slow down the process of updating screens. Any standard RR label code that you do not re-define, will be requested to RR to be processed as a normal label code, this allows you to use RR's labels within your plugin's skin (TRACKNAME etc) -- this however should be avoided in excess to prevent performance issues.
NOTE: it is important that your your label code be listed all in lowercase for it to be propperly processed. This is regardless of how you typed the command in the .skin file.
Creating a new INDICATOR code
Say for instance you'd like to create an indicator called "MYINDICATORCODE" to be used in your .skin file. All you have to do is:
-Locate the UpdateIndicators() function in frmSkin
-Locate the case statement under "Process Code". You should see the examples "INDICATORCODE1",etc created. All you have to do is uncomment the code, and replace the references to CURRENT_VALUE1 (3 of them) with whatever variable of function that provides the true/false (ON/OFF) states for the indicator code you're creating.
Say for instance you wanted to have an indicator to go ON if/when the current time of the day is in the morning (before noon / 12am). You could use this as your "morning" indicator code:
Note the three places you need to place the code that results in true/false for that indicator code. Still, that's all there's to it. You should probably copy/paste as many copies of the above as indicators you wish to have and just replace the "currentvalue" with the expressions to measure the desired status.
If Inds(C).LastState <> (Val(format(time, "HH")) < 12) Then
If (Val(format(time, "HH")) < 12) Then IPic = 2 Else IPic = 3
Inds(C).LastState = (Val(format(time, "HH")) < 12)
NOTE: it is important that your your indicator code be listed all in lowercase for it to be propperly processed. This is regardless of how you typed the command in the .skin file.