The resource editor API

This chapter lists the structures that support the resource editor plugin API, the functions exported by PhAB that support the API, and the functions you need to provide in your plugin.

Resource editor code is put in a DLL. You can put one, two, or more resource editors into a single DLL. Alternatively, you can put the frugal resource editor for a resource type in one DLL, and the full editor in another. Each DLL is organized as an addon that uses the Addon Interface API.

The DLL must declare the addon interface as:

#define RESPLUGIN_VERSION 202

AOInterface_t interfaces[]=
{
  { "PhAB Resource Editors", RESPLUGIN_VERSION, &tab },
  { 0,0,0 }
};

Note that the RESPLUGIN_VERSION is defined as 202.

The tab variable must point to an instance of the ResPlugin_t structure.

Resource Editor API structures

You have to provide all the methods defined in ResPlugin_t, ResPluginFrugalEditor_t, and ResPluginFullEditor_t in the resource editor plugin, otherwise PhAB will not load and use the plugin.

When a new plugin instance is created, it is given a pointer to a structure that is exported from PhAB to the plugin and contains functions that the plugin can call into PhAB. All these functions take at least a PhABHandle_t as an argument.

Functions defined in ResPlugin_t that you must provide in the plugin:

• ResPluginLoadingF_t -- a function called just after the DLL is loaded by PhAB into its address space, used to set up any resources common to the plugins in the DLL.
• ResPluginUnloadingF_t -- a function called before the DLL is unloaded from PhAB's address space. This function is called once for each successful call to ResPluginLoadingF_t.

Functions defined in ResPluginCommon_t that you must provide in the plugin:

• ResPluginSetDataF_t -- a function to set the data value in a resource editor.
• ResPluginDestroyF_t -- a function to destroy a resource editor and free any resources allocated.

Functions defined in ResPluginFrugalEditor_t that you must provide in the plugin:

• ResPluginFrugalCreateF_t -- a function to create an instance of a frugal resource editor.

Functions defined in ResPluginFullEditor_t that you must provide in the plugin:

• ResPluginAnyChangesF_t -- a function called by PhAB to determine whether the resource editor contains changes.
• ResPluginBlockF_t -- a function called by PhAB to tell the resource editor to temporarily block input.
• ResPluginDisableF_t -- a function called by PhaB to tell the resource editor to disable itself, and appear disabled (greyed out).
• ResPluginFullCreateF_t-- a function to create an instance of a full resource editor.
• ResPluginGetChangesF_t -- a function called by PhAB to retrieve any changes in the resource editor.
• ResPluginGetAreaF_t -- a function called by PhAB to find out the area of the resource editor window.
• ResPluginToFrontF_t -- a function called by PhAB to bring the resource editor window to the front.

Functions exported from PhAB

• alloc_image() -- called by a plugin to allocate memory for RES_DATATYPE_PIXMAP data.
• alloc_mem() -- called by a plugin to allocate memory for its copy of data.
• answer_changes() -- called by a plugin to answer PhAB's call to ResPluginAnyChangesF_t.
• apply() -- called by a plugin to apply its data to the widget in PhAB.
• closing() -- called by a plugin to tell PhAB that the resource editor will close (for example, the user clicked the Close button.)
• cmp() -- a function a plugin can use to compare two ResDatatype_t values.
• dup() -- a function a plugin can use to duplicate a ResDatatype_t value.
• free() -- a function a plugin can use to free a ResDatatype_t value.
• free_image() -- a function a plugin can use to free RES_DATATYPE_PIXMAP data allocated by alloc_image().
• free_mem() -- a function a plugin can use to free memory allocated by alloc_mem().
• get_res() -- a function to get resource data from another resource editor plugin, allowing one editor to use another as a "sub-editor".
• open() -- a function a frugal resource editor can call to open a full resource editor for its datatype.

The resource editor's window supporting functions

These functions are exported from PhAB in the PhABResExportFull_t structure, which is passed as a pointer when the plugin instance is created. They are convenience functions that a full editor can use in order to ensure a consistent look for the resource editor windows. We recommend that you use these functions to create and manage the editor window, except for the case when your plugin spawns an external application. In that case the external application should provide the window.

• create_window() -- a function that creates a window container which the plugin can use as the full resource editor window.
• destroy() -- a function to destroy the window created by create_window().
• get_area() -- a function to get the area of the window created by create_window().
• message() -- a function that displays a message in PhAB.
• set_state() -- a function to set the state of the window created by create_window().
• to_front() -- a function to bring the window created by create_window() to the front.