No announcement yet.

How do I use the Extension Plugin Interface ?

This topic is closed.
This is a sticky topic.
  • Filter
  • Time
  • Show
Clear All
new posts

  • How do I use the Extension Plugin Interface ?

    With the latest versions of RR it is now possible to make simple DLL files which extends the functionality of RR. You can make buttons, labels and indicators in such manner. If you wish to add features to RR that only use those objects, this may be the best interface method for you. The main benefits of this interface are:

    -Very simple code necessary to make it work (no need to look or understand much of how RR's code works).
    -Compatibility across different versions of RR, no need to recompile or add new code to make RR work with it.
    -No need to re-create user interface (skin support, objects etc).

    The code you make will basically be loaded through a simple skin definition that can be added to any existing skin as desired. The below loads the example extension plugin included in RR's sources:


    There are examples of extension plugins included with the installer, just select to install them during the install. If you need any help let us know, we'll be more than willing to help. You can also find the examples separately here (may be not up-to-date with the installer):

    The example extension adds three new button codes to RR:

    "MYCOMMAND" - Shows a message box with the current screen.
    "TEST" - Returns the "AUDIO" command to be executed in RR.
    "BOO" - Executes the "VOL+" command.

    Also adds the following label code:

    "MYLABEL" - Displays "Hello from Extension!" on a label.

    And adds the indicator code:

    "MYINDICATOR" - Displays/hides a gif file every other seconds. You may want to set the path to a valid GIF file to see how it works.

    By looking at the code, you'll notice that there's actually very little code in the project to do all the above. So here's a brief of how things work:

    The base of the extension plugin is the "RRExtension" class module. It is REQUIRED and needs to have that exact name. You can add as many classes, forms and objects as you like to the project -- and subsequently use it to execute any button codes and produce any information to be displayed on labels/indicators that you wish to display on any of RR's screens (for instance, the features added by the example plugin above can be used on ANY screen in RR).. The NAME used for the DLL and for loading the plugin in RR is actually the Project name of your VB project. So here are the basic steps to get your own plugin working in RR:

    -Make a copy of the Extension plugin sources folder to a folder in which you'll work on your project. (I.e. \RRPLUGIN\) -- that way you won't have to start from scratch and won't loose the original code for reference.
    -Delete MyExtension.dll (the original DLL)
    -Rename MyExtension.vbp to match your plugin name (i.e. RRPlugin.vbp)
    -Open the Project in VB
    -Click on the "MyExtension" project name (first line on project window -- may want to press CTRL+R to show it if hidden), then under the properties window (F4) change the "NAME" property to your plugin name (i.e. RRPlugin)

    Now, It is very important to read and understand the information/comments on top of each of the procedures. Those are the functions RR will call on your DLL in order to process a button/label/indicator code:

    -ProcessCommand(CMD as string, frm as Object)

    When entering this function CMD will have the button code to execute and frm will have the form object of the screen who requested the button to execute. Basically, there's a scope of case statements to catch and process "known" command (that your plugin will execute), and you don't have to do absolutely anything if it's not a code you wish to process. it is VERY important that the commands be listed in lowercase in the case statement (since it lcases it first). If you execute a command in your plugin and it was completed, you should return 2 on the function call to tell RR to process the next button code, if you also wish to exit the current screen, return 1 so does it for you. If you wish to have RR execute another code, set CMD and return 3 (even if you have executed code prior to then). Returning 0 (Zero) will tell RR that you did not process the button code and RR should process it elsewhere (default -- if you don't set processcommand before exiting the function).

    -ReturnLabel(LBL as string, FMT as string)

    This function is called with the label code and the format specified in the skin. Similarly to processcommand, return the TEXT you wish to display in the label for the label code provided. It is not possible to redefine a standard label code from RR, but you can monitor when those are being used.

    -ReturnIndicator(IND as string)

    This function is called with the indicator code specified in the skin. Return either "true", "false" or the path for the image file to display as the indicator. Returning "false" will also erase any images you may have displayed previously, but nothing prevents you from displaying one image for "true" and another image for "false".. or even create multiple images to indicate more than one state for that indicator.

    And here's a quick rundow on the example code..

    "mycommand" - this button code will display a message box with the name of the current screen (as the comment says, in frm.tag). Then it sets processcommand to 2 to tell RR the command has been completed.

    "test" - this button code will basically set the command to "AUDIO" and tell RR to execute that command instead (by setting processcommand to 3)

    "boo" - this button code executes a command in RR in a way that you could use from outside the ProcessCommand function, for instance in case an event is generated in your plugin that you wish to trigger a command in RR. If you need to execute a command in RR from outside this function, you should use the ComSend function much like in this code.

    "mylabel" - this label will simply display a message in the label, you could of course add code under this case statement to generate or pull any info you wish to display in the label then return the desired text.

    "myindicator" - This indicator alternates between a path to a GIF file to show in the indicator position and the "false" result to basically produce a pulsating GIF effect in RR's skin. If you return "true" RR will display the ON layer of the skin in the area defined for the indicator. If you return a PATH like in the example, RR will try to load the image in the defined area of the indicator. Return "false" to erase the ON layer or previous image path returned.

    That's basically all there is to it. Once your project is done, compile it and load it with the X definition in RR. You should be able to use your newly added button/label/indicator codes as desired. They should work on ANY screen with no limitations. If you wish to, you can execute initialization of your code in the Class_Initialize event, and the clean up code can be added on Class_Terminate event. Those will be generated automatically upon loading/unloading of your DLL.

    At some point, I may add support for sliders.. and if anything, may even be able to make list support.
    Ride Runner RR's Myspace

    "Being happy is not about having what you want, it's about wanting what you have."
    "The best things in life are always free - but that doesn't mean money can't buy you good things."