ResPluginFullCreateF_t

A function you must write to create an instance of a full resource editor

Synopsis:

typedef ResPluginHandle_t
ResPluginFullCreateF_t( PhABHandle_t phab ,
  const PhABResExportFull_t *exp,
  const ResPluginFormatData_t *format,
  int n_default,
  const void *default_value,
  PhArea_t *area,
  char *caption,
  int n,
  const void *value )

Description:

This function is exported in the ResPluginFullEditor_t structure.

This function is called to create a new instance of the full resource editor.

If necessary, format information is passed by format when the plugin instance is created. The format data depends on the data type. For example, for the RES_DATATYPE_FLAG datatype, format provides the plugin with the list of possible flag values, the flag manifests, and the associated masks, if any.

The data value is represented by the parameter pair n and value. How these parameters are passed depends on the data type of the resource. See the description of resource data types for a discussion of how these parameters are passed.

To ensure a consistent look for the full resource editors, PhAB provides a library of functions to support the resource editor's windowing requirements. For example, create_window() creates a typical resource editor window, complete with standard Cancel, Default, Apply, and Done buttons. The resource editor needs only to populate a container inside the typical window for its specific editing requirements.

You can choose to use these supporting functions or you can create your own window for the resource editor. You can even spawn an external application, pass it the data, and manage the external application as a resource editor in PhAB. This approach is described in the Plugin lifecycle section.

Arguments:

phab

A PhABHandle_t provided by PhAB, and which should be used as the phab argument when the plugin calls any of the functions present in the exp table of functions.

exp

A pointer to a PhABResExportFull_t defining the functions exported by PhAB for the full editor. You can assume that the exp pointer will remain valid during the lifetime of the plugin.

format

A pointer to a ResPluginFormatData_t structure that describes format information required by the data type.

n_default

Default value for the resource, together with the default_value argument.

default_value

Default value for the resource, together with n_default. This pointer is guaranteed to remain valid during the lifetime of the plugin.

area

A pointer to a PhArea_t representing the full resource editor area. The first time an editor ever runs, PhAB may pass the area argument as NULL, meaning that it has no records about this resource editor, and in this case you should use the area that best fits the editor.

After the first time the editor runs, PhAB saves the position and dimensions in /.ph/phab/abwspace.cfg, and on subsequent invocations the area is taken from the saved value. If you change the default size of the editor window, don't forget to erase your abwspace.cfg file so that the new default is used.

caption

A string related to the resource being currently edited. This string can be displayed as the window's title or maybe in a label inside the window.

n

Initial resource data, depending on the data type.

value

Initial resource data, depending on the data type.

Should return:

This function should return a ResPluginHandle_t plugin handle, or NULL on error. If you return a non-NULL value, this value is passed as the first argument to all your other functions.

Examples:

This sample create function for a full editor is from the complete plugin example at the end of this chapter.

static ResPluginHandle_t plugin_full_create
        ( PhABHandle_t phab , const PhABResExportFull_t *exp,
          const ResPluginFormatData_t *format,
          int n_default, const void *default_value,
          PhArea_t *area, char *caption,
          int n, const void *value )
{
  PluginFullInstance_t *instance;
  PtWidget_t *parent;
  PhRect_t offset = { { 0, 0 }, { 0, 0 } };
  PhArea_t tarea;
  PtArg_t args[1];
  int start = 0, end = n;

  instance = calloc( 1, sizeof( *instance ) );
  if( !instance ) return NULL;

  instance->n_default = n_default;
  instance->default_value = default_value;
  instance->n_master = n;
  instance->value_master = value;

  instance->phab = phab;
  instance->exp = exp;

  if( !area ) {
    PhRect_t rect;
    PhWindowQueryVisible( 0, 0, 0, &rect );
    tarea.pos.x = rect.ul.x + 100;;
    tarea.pos.y = rect.ul.y + 100;
    tarea.size.w = 340;
    tarea.size.h = 150;
    area = &tarea;
    }
  instance->convenience_handle = exp->create_window( phab, area, caption, 0, &parent,
                                                     plugin_full_notify, instance );

  PtSetParentWidget( parent );
  PtSetArg( &args[0], Pt_ARG_ANCHOR_OFFSETS, &offset, 0 );
  instance->full= ApCreateWidgetFamily( db, "string_full_container", 0, 0, 1, args );
  instance->full_widget = PtWidgetChildFront( instance->full );
  PtAddCallback( instance->full, Pt_CB_RESIZE, plugin_full_resize, instance );
  PtAddCallback( instance->full_widget, Pt_CB_TEXT_CHANGED, plugin_full_changed,
                 instance );
  PtAddCallback( instance->full_widget, Pt_CB_ACTIVATE, plugin_full_done, instance );

  PtSetResource( instance->full_widget, Pt_ARG_TEXT_STRING, value, 0 );
  PtTextSetSelection( instance->full_widget, &start, &end );
  PtRealizeWidget( instance->full );

  set_state( instance, value );

  return ( ResPluginHandle_t ) instance;
}

Classification:

QNX Neutrino

See also:

create_window(), PhABResExportFull_t, PhArea_t, ResPluginFullEditor_t.