
		      _____  _             _
		     |  __ \| |           (_)
		     | |__) | |_   _  __ _ _ _ __  ___
		     |  ___/| | | | |/ _` | | '_ \/ __|
		     | |    | | |_| | (_| | | | | \__ \
		     |_|    |_|\__,_|\__, |_|_| |_|___/
				      __/ |
				     |___/


			   by Shawn Hargreaves




Introduction
------------

   It is very easy to extend the grabber and other datafile tools by writing 
   new plugin modules. These can add support for totally new types of 
   object, or they can just provide some additional import/export routines 
   to make one of the existing types work with a wider range of file 
   formats. Plugins are also capable of hooking into the grabber menu 
   system, either by adding new functionality to one of the existing menus 
   or by creating whole new menu options of their own.

   Most of the standard grabber functionality is in fact implemented as 
   plugin modules. Try commenting out the contents of all the .inc files in 
   this directory, and then recompiling the grabber: you will find that 
   several of the menu items have gone missing, and it won't recognise 
   anything other than the basic file and binary data objects!

   This file is not a complete manual for the plugin architecture. It 
   assumes that you already have a pretty good idea about how datafiles and 
   the GUI system operate, and that you aren't afraid of reading sources to 
   learn how they work. Your best bet is to have a look through datedit.h 
   to see what functions are available, and then use one of the existing 
   plugins as a basis for your addition. Using this file together with the 
   sources should be enough to get you going, but as always, feel free to 
   ask for help if you get stuck...



The Basics
----------

   A plugin is implemented as a collection of files which are copied into 
   the tools/plugins directory, and will automatically be linked into the 
   grabber, dat utility, and other datafile tools. To install a plugin, you 
   can simply copy it to the plugins directory and then rebuild Allegro.

   At the very least, you must provide a .c source file and a .inc setup 
   file. The .inc file will be included directly into datedit.c, and will be 
   executed once when the system initialises. From here you can call 
   whatever routines are needed to activate your plugin, which will usually 
   include at least one of the datedit_register_*() functions.

   If a plugin makes use of external libraries, it can also provide a .scr 
   command file, which contains whatever additional linker options your 
   plugin requires.

   There are no restrictions on what names you can give these files other 
   than the required extensions, but to minimise the danger of namespace 
   conflicts I recommend that you stick to my convention of calling them 
   dat{type}.*, where {type} is the ID for the type of object being 
   implemented by this plugin.

   There are three types of plugin interface, which can be used together or 
   in isolation. Object plugins add totally new types of datafile object, 
   and provide all the functions needed to manipulate and display this data. 
   Import/Export plugins provide the ability to read and write data from 
   external file formats, and can be used to add import and export functions 
   for both the predefined and custom object types. Finally, menu plugins 
   respond to user interface actions in the grabber, and can either hook 
   into the existing menu system or add completely new menu options of their 
   own.



Object Plugins
--------------

   An object plugin is installed by calling the function:

      void datedit_register_object(DATEDIT_OBJECT_INFO *info);

   These plugins are defined by a header structure in the form:

      typedef struct DATEDIT_OBJECT_INFO
      {
	 int type;
	 char *desc;
	 void (*get_desc)(DATAFILE *dat, char *s);
	 void *(*makenew)(long *size);
	 void (*save)(DATAFILE *dat, ..., PACKFILE *f);
	 void (*plot)(DATAFILE *dat, int x, int y);
	 int (*dclick)(DATAFILE *dat);
	 void (*dat2s)(DATAFILE *dat, char *name, FILE *file, FILE *header);
      } DATEDIT_OBJECT_INFO;

   Object plugins add support for completely new types of object, and it 
   does not make sense to install more than one of these for the same type 
   ID (if you do, the second plugin will simply never be used).

   The fields in this structure are:

   'type'
      The object type ID, as produced by the DAT_ID() macro.

   'desc'
      ASCII description of this object type.

   get_desc()
      Optional. Fills 's' with a description of the object. Implementing 
      this function allows you to provide a more detailed description (eg. 
      "32x32x8 bitmap" rather than just a generic "bitmap"). If you leave it 
      NULL, the 'desc' field will be displayed instead.

   makenew()
      Creates and returns a pointer to a new object of this type, and if the 
      object is going to use it, sets 'size' to the object size in bytes.

   save()
      Saves the object into an Allegro datafile. This takes quite a lot of 
      parameters, but you can ignore all of them except the 'dat' and 'f' 
      values: the others are only needed for nested datafiles.

   plot()
      Optional. Draws the object onto the grabber screen at the specified 
      location. You must be careful to make sure that this routine will work 
      in all screen resolutions and color depths!

   dclick()
      Optional. Called when the user double-clicks on an object in the 
      grabber.

   dat2s()
      Optional. Used by the dat2s utility to convert an object into 
      assembler source code. If you don't implement this, your custom object 
      type will not be supported by dat2s.

   You will notice that this interface does not provide any support for 
   loading these objects from datafiles, or for reading/writing external 
   file formats. That is because the datafile loading is handled internally 
   by the core Allegro lib (you should use register_datafile_object() to 
   install your load handler), and the import/export is handled by a 
   different type of plugin (see below).

   The 'datsample_info' interface from datsamp.c is a good basic example of 
   an object plugin.



Import/Export Plugins
---------------------

   An import/export plugin is installed by calling the function:

      void datedit_register_grabber(DATEDIT_GRABBER_INFO *info);

   These plugins are defined by a header structure in the form:

      typedef struct DATEDIT_GRABBER_INFO
	 {
	    int type;
	    char *grab_ext;
	    char *export_ext;
	    void *(*grab)(char *filename, long *size, ...);
	    int (*export)(DATAFILE *dat, char *filename);
	 } DATEDIT_GRABBER_INFO;

   Import/export plugins add file format support to existing types of 
   object. You will usually need at least one of these for each object 
   plugin that you install, but you can also use them to extend the 
   predefined object types. There is no limit on how many import/export 
   plugins can be attached to a single type of object, or on how many file 
   formats can be supported by a single plugin.

   The fields in this structure are:

   'type'
      The object type ID, as produced by the DAT_ID() macro.

   'grab_ext'
      List of the file extensions that are supported for reading data, 
      separated by semicolons. May be left blank if this plugin only 
      provides export functions.

   'export_ext'
      List of the file extensions that are supported for saving data, 
      separated by semicolons. May be left blank if this plugin only 
      provides import functions.

   grab()
      Reads a new object from the named file, returning a pointer to it. If 
      this type of object requires it, also sets 'size' to the size of the 
      object in bytes.

   export()
      Saves an object into the named file.

   The 'datfont_grabber' interface from datfont.c is a good example of an 
   import/export plugin that supports several different file formats.



Menu Plugins
------------

   A menu plugin is installed by calling the function:

      void datedit_register_menu(DATEDIT_MENU_INFO *info);

   These plugins are defined by a header structure in the form:

      typedef struct DATEDIT_MENU_INFO
      {
	 MENU *menu;
	 int (*query)(int popup);
	 int flags;
	 int key;
      } DATEDIT_MENU_INFO;

   Menu plugins are based on the Allegro GUI menu structure. If you install 
   a plugin for a menu option that already exists, it will hook into the 
   existing menu, but you can also add completely new options by specifying 
   a totally new menu text string.

   The fields in this structure are:

   'menu'
      Points to the Allegro menu structure for this option. Note that this 
      is only one single menu item, not a whole array of entries. The flags 
      and dp fields from this structure will be overridden by the grabber, 
      but you must fill in the text field with your menu text string, and 
      either the proc function pointer with your action routine (for simple 
      command menus like the "grab" function), or the child field with a 
      pointer to a nested menu (for hierarchical structures like the "new" 
      menu).

   query()
      Optional. If not NULL, this routine will be called to check whether 
      this plugin command is suitable for use in the current situation. For 
      normal pulldown menus, the 'popup' parameter will be FALSE, and you 
      have a chance to either return TRUE, in which case your command will 
      be used, or FALSE, in which case the default processing will be 
      carried out (this allows a plugin to take over standard commands like 
      "grab", but reject them when anything other than their specific type 
      of object is selected, so that the normal grab command will still work 
      for other object types). For popup (right mouse button) menus, this 
      routine will be called immediately before the menu is displayed, with 
      the 'popup' parameter set to TRUE. If you return FALSE from this call, 
      your command will not be included in the popup (this is how things 
      like 'autocrop' are able to only appear when you right-click on a 
      bitmap object).

   'flags'
      Indicates where in the menu system you would like your command to be 
      added. This is a bitfield containing any combination of the values:

	 DATEDIT_MENU_FILE    - add it to the File menu
	 DATEDIT_MENU_OBJECT  - add it to the Object menu
	 DATEDIT_MENU_HELP    - add it to the Help menu
	 DATEDIT_MENU_POPUP   - include it in right-click popup menus
	 DATEDIT_MENU_TOP     - a new entry in the topmost menu bar

   'key'
      If non-zero, this is the ASCII code of a keyboard shortcut for your 
      command. Please be cautious in your use of these, because if several 
      plugins try to hook the same keyboard shortcut, obviously only one of 
      them is going to be able to get it :-)

   The 'datworms_menu' interface from datworms.c is a good example of how to 
   add a new menu command, and 'datpal_grabber_menu' from datpal.c shows how 
   to hook into an existing command (it adds a custom function so that 
   palettes can be grabbed from a previously read bitmap, rather than 
   directly from a disk file).



Misc
----

   Bear in mind that these plugins are used by that dat, dat2s, and pat2dat 
   utilities as well as the grabber, so you cannot assume anything about the 
   system setup while your code is run. The menu commands and view/dclick 
   functions will only ever be used in a graphics mode (but this could be 
   any resolution and color depth), and the other functions may equally well 
   be called from a graphics or text mode environment.

   For displaying messages, errors, prompting the user for input, etc, use 
   the datedit_msg(), datedit_error(), and datedit_ask() functions. These 
   are implemented as printf() calls by the text mode utilities and as alert 
   boxes by the grabber, so they will work correctly in any situation.

   There are lots of useful helper functions in datedit.h. Perhaps most 
   importantly when implementing menu commands, grabber_single_selection() 
   returns a pointer to the currently selected object (NULL if there is a 
   multiple selection), and grabber_foreach_selection() iterates through 
   every selected object, using a callback function to let you process 
   multiple objects with a minimum of hassle.



And Finally
-----------

   Good luck!
