Getting Started

Overview

This page provides a description of application programming with the Centrafuse Software Development Kit. The CF SDK is used to create Centrafuse "Plugins", which are just class libraries that implement the CFPlugin interface.

Plugins compiled for Centrafuse reference the CFPlugin dll, included in this SDK in the root directory. The CFPlugin dll provides the developer with all of the necessary interfaces and classes to create functional pieces to work in conjunction with Centrafuse software. For example, popular plugins that already exist are SkinBrowser, LogoDashboard, and FileSync. Satellite Radio is also implemented in CF as a plugin. Radio support is added through use of a plugin. Basically anything a developer can imagine can be added to CF.

What's the Easiest Way to Get started?

The easiest way to get started with your own plugin is to simply copy the HelloWorld (or SimpleList) project to a new directory, do some renaming of the the files to coordinate with your plugin project, and start making modifications to the source code.

SDK Development Tools

This SDK uses the following development environments for it's example build files:

• Visual Studio 2005 (Version 8) or .NET2 compiler
• .NET2 Framework.
• Knowledge of a programming language, either C#, VB, or C++

Note all project files are currently configured to copy builds to the Binaries directory in the root of SDK/Examples and SDK/Flash.

A Visual Studio Solution file containing all projects in the SDK can be found in the root SDK directory. This solution file contains references to all plugin examples, all languages, and the Flash plugin project.

Convention

CFPlugin functions that are prefixed by CF_* are those that are part of the User Interface's useable API. CFPlugin functions that are not prefixed by CF_* are, in most cases, only to be used internally by the Centrafuse Plugin Layer.

CFSetup also abides by this convention.

Static classes such as Win32 and CFTools are also part of the useable API.

SDK Directory Structure

The directory structure of the SDK is logically laid out for ease of use. This is depicted and described below:

Content	Directory Location
Microsoft HTML Help Document	/SDKROOT/Doc
HTML Documentation	/SDKROOT/Doc/html
Examples	/SDKROOT/Examples
Example Source Code	/SDKROOT/Examples/Source
Example Compiled Binaries	/SDKROOT/Examples/Binary
3rd Party Applications	/SDKROOT/3rdPartyApps
Flash/Shockwave Plugin SDK	/SDKROOT/Flash
Graphics Files and PSD's	/SDKROOT/Graphics

The contents of the "Doc" folder contains 2 forms of documentation for the CF SDK, a microsoft help compiled chm file, and plain vanilla html documentation, located in the html subfolder.

The contents of the "Examples" folder are sample applications plugins written for Centrafuse. The goal of the Examples directory is to provide sample plugins in various languages. C#, VB, C++, and Delphi are target languages to provide examples for, although as of the initial release, only C# examples are included. Stay tuned for future releases for additional examples and using other languages other than C#.

The contents of the "Flash" folder is a simple SDK to develop flash movies that can communicate with Centrafuse. Already provided are working examples, flash project files, project files for the class library interface, and sample flash movies to use.

The contents of the "Graphics" folder are graphics files that can be used in creating plugins to match the default CF skin, Aura.

The contents of the "3rdPartyApps" folder are applications written by 3rd parties for use in developing CF plugins, and testing hardware that CF is compatible with. These applications are not supported by Flux Media, and should be used at your own discretion.

Class Libraries and Inheritance

Class library projects in .NET produce a dll library object that Centrafuse can load at runtime, thus "plugging in" to Centrafuse. These dll's "inherit" Centrafuse Plugins classes from the cfplugin.dll class library. For example, your plugin screen will inherit the CFPlugin class, and your Settings screen for your plugin inherits from CFSetup. Inheriting from these classes give your plugin an interface to control Centrafuse functionality, call Centrafuse skinning functions, etc, etc...

The Plugin constructor

Your plugin dll will contain a main class that inherits from CFPlugin, and it will contain a constructor where a variey of Plugin flags can, or must, be set.

 public HelloWorld()
 {
     // When set to true all system audio will be paused when the plugin is shown.  The main title,
     // position,and status labels will be cleared and can be populated by the plugin.
     this.CF_pluginPauseAudioFlag = false;
                        
     // The plugin name should have a matching section in the skin.xml file.
     this.CF_pluginName = "HELLOWORLD";
                        
     // Sets the plugin to be a GUI plugin.  Only GUI plugins are available button actions.
     this.CF_pluginIsGUI = true;
 
     // Set Settings flags, show in basic settings and advanced settings
     this.CF_pluginHasSettings = true;
     this.CF_pluginHasBasicSettings = true;
 
     // Create XML Configuration if not exists
     AddConfigXml();
 }

The CFPlugin Interface Functions

Your plugin dll will inherit many functions from CFPlugin (or in the case of settings screen, CFSetup). For this writing we will reference the class that references CFPlugin. These inherited functions are all prefixed with CF_plugin*, and they make up the core interface between your plugin dll and Centrafuse. Some examples are:

• CF_pluginInit() - Called by Centrafuse to initialize the plugin once it is instantiated with it's constructor
• CF_pluginShow() - Called by Centrafuse when the plugin screen is being shown
• CF_pluginClose() - Called when Centrafuse is exiting, cleanup should be performed
• CF_pluginShowSetup() - Called when the plugin's settings page needs to be shown

The complete list of these interface functions can be found in the CFPlugin Documentation.

CFPlugin Interface Functions: The CF_pluginInit() Override

The CF_pluginInit() function shall load settings, skins, build controls, etc. This function is called once when Centrafuse is first loaded. Typically, in the example source code, the LoadSettings() function is called to read the config file, set up and load skin images, and set up Centrafuse event handlers. Also included in the LoadSettings() function in the examples is code to check the current Centrafuse skin and language, because in the case that it was changed, in that particular runtime, the plugin will not have known about it.

 public override void CF_pluginInit()
 {
     CFTools.writeModuleLog("HelloWorld: CF_pluginInit", LogFilePath);
     try
     {
         // loads Settings
         LoadSettings();
         // add event handlers for keyboard and power mode change
         this.CF_Event_powerModeChanged +=new Microsoft.Win32.PowerModeChangedEventHandler(HelloWorld_CF_Event_powerModeChanged);
         this.KeyDown += new KeyEventHandler(HelloWorld_KeyDown);
     }
     catch(Exception errmsg) { CFTools.writeError(errmsg.ToString()); }
 }

CFPlugin Interface Functions: The CF_pluginShowSetup() Override

The CF_pluginShowSetup() function is used to display plugin settings to the user. The plugin code is responsible for displaying the Settings dialog using derivation from the CFSetup class, in the examples, this is done via the file Setup.cs, Setup.vb, and Setup.cpp depending on the programming language used. The plugin code is also responsible for saving any changed settings once the dialog is closed. The Setup dialog is implemented by the plugin by creating a class that derives from CFSetup. This is explained in the section Setup/Settings

 public override DialogResult CF_pluginShowSetup()
 {
     CFTools.writeModuleLog("HelloWorld: CF_pluginShowSetup", LogFilePath);
                        
     // Return DialogResult.OK for the main application to update from plugin changes.
     DialogResult returnvalue = DialogResult.Cancel;
 
     try
     {
         // Creates a new plugin setup instance. If you create a CFDialog or CFSetup you must
         // set its MainForm property to the main plugins MainForm property.
         Setup setup = new Setup();
         setup.MainForm = this.MainForm;
         setup.setupSection();
         returnvalue = setup.ShowDialog();
         if (returnvalue == DialogResult.OK)
         {
             // add code here for saving the modified settings
 
             // Reloads plugin configuration.
             LoadSettings();
         }
         setup.Close();
         setup = null;
     }
     catch(Exception errmsg) { CFTools.writeError(errmsg.ToString()); }
 
     return returnvalue;
 }

See also:

Setup / Settings

Controlling Centrafuse Features with CF_systemCommand()

Many Centrafuse features can be controlled simply with the CF_systemCommand() function. The CF_systemCommand() function takes one CF_Actions parameter, and an optional extra 1, 2, 3, or 4 string parameters, these being specific to the CF_Actions used. See the CF_Actions Documentation for a complete list of CF_Actions and command specific parameters associated with each individual command.

 private void HelloWorld_BTN5_Click(object sender, MouseEventArgs e)
 {
     // The Button #5 has been clicked...
     CFTools.writeModuleLog("HelloWorld: BTN5 clicked.", LogFilePath);
     try
     {
         // Display a status box that will autohide
         this.CF_systemCommand(CF_Actions.SHOWINFO, "Status Info Text", "AUTOHIDE");
     }
     catch (Exception errmsg) { CFTools.writeError(errmsg.ToString()); }
 }

The CF_systemCommand() function is also used in Plugin-to-Plugin communication to issue commands to any running Centrafuse Plugins.

See also:

Plugin Communication, CF_Actions