$Id$
               __________               __   ___.
     Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
     Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
     Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
     Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
                       \/            \/     \/    \/            \/

                            Plugin API summmary

Plugin API Version 26
(backwards compability up to version 25)

Info: To get the latest plugin api specs:
look at struct plugin_api in apps/plugin.h
(and apps/plugins/helloworld.c for an example)

Plugin Skeleton
===============

#include "plugin.h"

static struct plugin_api* rb;

//plugin entry point
enum plugin_status plugin_start(struct plugin_api* api, void* parameter)
{
    TEST_PLUGIN_API(api);
    (void)parameter;
    rb = api;
    
    //insert your code here
    
    return PLUGIN_OK;
}

to call a function, use the plugin_api structure this way :  rb->function()

Plugin Internals
================

  int version;

     Plugin version number.

  int plugin_test(int api_version, int model, int memsize);

     This function is called by the TEST_PLUGIN_API() macro to test
     compability of the plugin with current software.
     Returns PLUGIN_OK if plugin is supported.
     Returns PLUGIN_WRONG_API_VERSION if plugin version isn't compatible.
     Returns PLUGIN_WRONG_MODEL if the model or memsize is wrong.

LCD
===

  Generic
  -------

    Most LCD functions are specific for which output we work with, due to the
    huge differences.

    void lcd_clear_display(void);
      
      Clear the whole display
   
    void backlight_on(void);
      
      Turn the backlight on
   
    void backlight_off(void);
      
      Turn the backlight off
   
    void splash(int ticks, bool center, char *fmt, ...);
      
      Display a formated string in a box durring time ticks. If center is
      FALSE, the display is left justified. If center is TRUE, the display
      is centered horizontaly and verticaly. The string is formated as with
      the printf function.
      (There are HZ ticks per second)
   
    void lcd_puts(int x, int y, const unsigned char *string);
      
      Write a string at given character position.
   
    void lcd_puts_scroll(int x, int y, unsigned char* string);
      
      Print a scrolling string at screen coordinates (x,y). The scrolling
      style is STYLE_DEFAULT.
   
    void lcd_stop_scroll(void);
      
      Stop all scrolling lines on the screen.
   
    void lcd_set_contrast(int val);
      
      Set the screen contrast. Argument val should be a value between
      MIN_CONTRAST_SETTING and MAX_CONTRAST_SETTING.

  Recorder
  --------
 
    All the functions operate on a display buffer. You make the buffer get
    shown on screen by calling lcd_update().

    void lcd_update(void);
   
       Update the LCD according to the internal buffer.

    void lcd_update_rect(int x, int y, int width, int height);

       Update the given rectangle to the LCD. Give arguments measured in
       pixels. Notice that the smallest vertical resolution in updates that the
       hardware supports is even 8 pixels. This function will adjust to those.

    void lcd_setfont(int font);
   
       Set default font
      
    struc font* font_get(int font);

       Return a pointer to an incore font structure. If the requested font
       isn't loaded/compiled-in, decrement the font number and try again.
      
    void lcd_putsxy(int x, int y, const unsigned char *string);
   
       Put a string at given coordinates.
   
    void lcd_puts_style(int x, int y, const unsigned char *str, int style);

       Put a string at given coordinates. Intger style can be STYLE_DEFAULT
       for black text display or STYLE_INVERT for white text display.
      
    void lcd_puts_scroll_style(int x, int y, unsigned char* string, int style);
  
      Same as lcd_puts_style and scrolling is enabled.
      {new in plugin API version 26}
      
    void lcd_bitmap(const unsigned char *src, int x, int y, int width,
                    int height, bool clear);
   
       Put a bitmap at given coordinates. If clear is true, the area is
       cleared before the bitmap is put.
       Element src[i] is the binary representation of column number i of
       the bitmap read from bottom to top.
   
    void lcd_clearrect(int x, int y, int width, int height);
   
       Clear a rectangle area.
   
    void lcd_fillrect(int x, int y, int width, int height);
   
       Fill a rectangle area.
      
    void lcd_drawrect(int x, int y, int width, int height);
   
       Draw a rectangle.
    
    void lcd_invertrect(int x, int y, int width, int height);
   
       Revert the graphics of the given area.
      
    void lcd_drawline(int x1, int y1, int x2, int y2);
   
       Draw a line between the coordinates.
      
    void lcd_clearline(int x1, int y1, int x2, int y2);
   
       Clear a line between two coordinates.
      
    void lcd_drawpixel(int x, int y);
   
       Draw a pixel on the given coordinate.
      
    void lcd_clearpixel(int x, int y);
   
       Clear the pixel at the given coordinate.
      
    int lcd_getstringsize(const unsigned char *str, int *w, int *h);

       Get the height and width of string str as it would appear on display.
       Return value is the width.
      
    void scrollbar(int x, int y, int width, int height, int items,
                   int min_shown, int max_shown, int orientation);
      
       Print a scroll bar at coordinates (x,y) of size width*height.
       orientation can be VERTICAL for a vertical scroll bar or anything else
       for a horizontal scroll bar.
       Item is the total number of items which the scroll bar refers to,
       min_show the rank of the first item displayed and max_show the 
       rank of the last displayed item.
      
    void checkbox(int x, int y, int width, int height, bool checked);

       Draw a checkbox area. If checked is TRUE, the checkbox is drawn
       checked !
      
    void lcd_blit(unsigned char* p_data, int x, int y, int width,
                  int height, int stride);
   
       ??? (see firmware/drivers/lcd-recorder.c:168)
      
    void lcd_roll(int pixels);
   
       Rolls up the lcd display by the specified amount of lines.
       Lines that are rolled out over the top of the screen are rolled in
       from the bottom again. This is a hardware remapping only and all
       operations on the lcd are affected.
       The screen is rolled up of pixel lines. The value must be between
       0 and LCD_HEIGHT.
       [Not for simulator]

  Player
  ------

    void lcd_define_pattern(int pat, char *pattern);
   
       Define a custom pattern of index pat. char *pattern is a 8x8 pixel
       bitmap.

    unsigned char lcd_get_locked_pattern(void);

       Get a locked pattern index.
       (see firmware/drivers/lcd-player.c:382)
      
    void lcd_unlock_pattern(unsigned char pat);

       Unlock pattern of index pat.
      
    void lcd_putc(int x, int y, unsigned char ch);

       Put character c at coordinates (x,y).
      
    void lcd_put_cursor(int x, int y, char cursor_char);

       Put cursor at coordinated (x,y).
       See firmware/export/lcd.h for possible cursor_char values.
      
    void lcd_remove_cursor(void);

       Remove the cursor from the screen.
      
    void lcd_icon(int icon, bool enable);

       ??? (see firmware/drivers/lcd-player.c:463)


Buttons
=======

  These functions work the same regardless of which keypad you have, but they
  return a different set of values. Note that the Recorder keypad has 10