Developing plugins

[sub]

Beginning of February was the target to put out an SDK of sorts, but I'm a bit behind schedule. It'll just consist of a couple of samples and some of classes to make things a little easier.

If you want to get started developing a plugin before this SDK, you can start developing a class which implements the following interface.


namespace GBPVR.Public
{
/// <summary>The IMenuTask is the interface that all GBPVR menu tasks implement</summary>
public interface IMenuTask
{
/// <summary>Returns the name of task, which is shown on the task's button</summary>
string getName();

/// <summary>Returns a short description about the purpose of the task</summary>
string getDescription();

/// <summary>Returns an image that represent the task. </summary>
Image getTaskImage();

/// <summary>Is called by GBPVR to get the task to render the screen to show the user.
/// Set requiresMoreRendering to true to render a series of screen (simple animation)</summary>
Image render(out bool requiresMoreRendering);

/// <summary>
/// Is called by GBPVR in response to a key being pressed while this
/// task is active. The task should return true if it has performed some action
/// as a result of the key press - which will inturn cause the task to be render()'d
/// </summary>
bool OnKeyDown(System.Windows.Forms.KeyEventArgs e);

/// <summary>Is called by GBPVR when the user has click'd somewhere on the page</summary>
void OnClick(System.Drawing.Point location);

/// <summary>Is called by GBPVR when the user has double click'd somewhere on the page</summary>
void OnDoubleClick(System.Drawing.Point location);

/// <summary>Is called by GBPVR when the task is activated.</summary>
void Activate();

/// <summary>Is called by GBPVR when the task is deactivated.</summary>
void Deactivate();

/// <summary>
/// This method is used to inform the active task of mouse wheel actions for scrolling etc...
/// </summary>
/// <param name="e">Mouse args that can be used for information about the mouse action</param>
void OnMouseWheel(MouseEventArgs e);
}
}


If you have any questions just ask...

[sub]

Below is a slightly more fleshed out example, which shows how the the interface above might be implemented. (BTW Sorry about the forum software stripping the tabbing from the source code - it makes it a bit difficult to read)

using System;
using System.Windows.Forms;
using System.Drawing;

using Public;

namespace MamePlugin
{
/// <summary>
/// Simple demonstration plugin
/// </summary>
public class MamePlugin: IMenuTask
{
private Image screenImage = null;
private Image taskImage = null;

public MamePlugin()
{
// constructor
}

/// <summary>Returns the name of task, which is shown on the task's button</summary>
public string getName()
{
// return some text to show on the button for this task
return "Mame";
}

/// <summary>Returns a short description about the purpose of the task</summary>
public string getDescription()
{
// return a description to show on the bottom of the main menu screen
return "Play your favorite retro arcade games";
}

/// <summary>Returns an image that represent the task. </summary>
public Image getTaskImage()
{
// usually I load an image called task.png, but no skins use this at the moment so I'll skip this in the sample

// if (taskImage == null)
// {
//   taskImage = Image.fromFile(skinDirectory + "\\task.png"
// }

return taskImage;
}

/// <summary>Is called to get the task to render the screen to show the user.
/// This function really provides the guts of the task, and should generate a screen based on
/// current state. This state is typically manipulated through OnKeyDown (or the mouse events)
/// This method should return a System.Drawing.Bitmap of ideally 720x480. Other sizes
/// will be slightly slower (as resizing would be required).
/// Set requiresMoreRendering to true to render a series of screen (simple animation)</summary>
public Image render(out bool requiresMoreRendering)
{
// allocate screen bitmap if we dont alerady have one
if (screenImage == null)
{
screenImage = new Bitmap(720,480);
}

// get graphics for drawing screen and clear the background
Graphics g = Graphics.FromImage(screenImage);
g.Clear(Color.Black);

// render some sample text
g.DrawString("This is a sample plugin", new Font("Tahoma", 14), new SolidBrush(Color.White), 50, 50);

// we're not attempting to animate so...
requiresMoreRendering = false;

// return screen for rendering
return screenImage;
}

/// <summary>
/// Is called in response to a key being pressed while this
/// task is active. The task should return true if it has performed some action
/// as a result of the key press - which will inturn cause the task to be render()'d
/// </summary>
public bool OnKeyDown(System.Windows.Forms.KeyEventArgs e)
{
bool handled = true;

switch (e.KeyCode)
{
case Keys.Enter:
// ... do something
break;

case Keys.Up:
// ... do something
break;

case Keys.Down:
// ... do something
break;

case Keys.Left:
// ... do something
break;

case Keys.Right:
// ... do something
break;

default:
handled = false;
}

return handled;
}

/// <summary>Is called when the user has click'd somewhere on the page</summary>
public void OnClick(System.Drawing.Point location)
{
// this sample doesnt do anything with mouse clicks
}

/// <summary>Is called when the user has double click'd somewhere on the page</summary>
public void OnDoubleClick(System.Drawing.Point location)
{
// this sample doesnt do anything with mouse clicks
}

/// <summary>Is called when the task is activated.</summary>
public void Activate()
{
// refresh list of available ROMs
}

/// <summary>Is called when the task is deactivated.</summary>
public void Deactivate()
{
// nothing required here...
}

/// <summary>
/// This method is used to inform the active task of mouse wheel actions for scrolling etc...
/// </summary>
/// <param name="e">Mouse args that can be used for information about the mouse action</param>
public void OnMouseWheel(MouseEventArgs e)
{
// this sample doesnt do anything with mouse events
}
}
}

[Dai]

Thanks for the sample code, all seems straight forward except for a couple of questions about rendering.

What causes 'render' to be called, is it after specific events or is it on a timed basis? If I have objects which change state for some reason other than the events you pass via the interfaces I will need to render again, if I just wait for the next 'render' call, could I be waiting long.

If I set RequiresMoreRendering, will 'render' be called again after a given time, I presume that is how simple animation would work.



Thanks

Dai

[sub]

The render is called after any of the keyboard or mouse events. There is another method which returns a flag indicating whether the plugin should autorender every seconds or so, but I deleted from the post because I was thinking about changing it. If you need this functionality, just assume its there (add a "public bool NeedsRegularRenderering()" method) - but there might be a few small changes.

[sub]

RequiresMoreRendering will cause the render method to be called pretty much straight away (100ms or so).

[Dai]

Thanks

[msm]

Looks good. Now if i could only finish my skin i might have a dabble with this

Excellant work as usual

Matt

[CodeMonkey]

I tried to build the C# weather sample plugin but it is missing 'GBPVR.Public'. Could you please post this file?

Thanks.

[sub]

Its included with the release (GBPVRPublic.dll), but you'll probably need to change the reference point to the file on your machine. The files is in a different place on my machine.

[CodeMonkey]

Yup, that was it, thanks