hid package

The hid package has two purposes:

it is glue layer for exporter dialog boxes and attribute dialog boxes;
it can register exporter HIDs in PCB

Building a custom dialog box

First hid_create() needs to be called. It returns a new hid_t, which is an opaque structure for the package that is used to describe attributes of an attribute dialog or an exporter hid. Attributes are added using hid_add_attribute(), which returns an unique ID of the attribute. The attribute ID can be used later for querying attribute value set by the user using hid_get_attribute().

The process of building a dialog box is closed by a call to

hid_register(), which registers a new exporter hid using the attributes of the dialog box; or
dialog_attribute() (of the dialog package) which pops up a custom dialog box immediately.

Registering an exporter

Function hid_register() registers the hid as an exporter. Should be called after all attributes have been added using hid_add_attribute(). The export is coordinated by pcb core; when the user request an export using the exporter, a series of events are delivered to the script:

envelope events to set up exporting
many draw events to actually export the objects
an envelope event to finish exporting

Envelope: events generated before or after exporting

HIDE_get_export_options(void *hid): Generated before get_exporter_options returns the option list to the GUI hid
HIDE_do_export_start(void *hid): Generated before export redraw starts
HIDE_do_export_finish(void *hid): Generated after export redraw finished

Drawing: events generated during exporting

Note: there may be multiple gcs (graphic contexts), each having its own color, line properties, xor drawing and faded state. Graphic contexts are created and destroyed by the following events:

HIDE_make_gc(void *hid, void *gc);
HIDE_destroy_gc(void *hid, void *gc);

Gc properties are changed by the following events:

HIDE_set_layer(void *hid, const char *name, int group);
HIDE_set_color(void *hid, void *gc, const char *name);
HIDE_set_line_cap(void *hid, void *gc, EndCapStyle style);
HIDE_set_line_width(void *hid, void *gc, int width);
HIDE_set_draw_xor(void *hid, void *gc, int xor);
HIDE_set_draw_faded(void *hid, void *gc, int faded);

Finally, the actual drawing operations:

HIDE_draw_line(void *hid, void *gc, int x1, int y1, int x2, int y2);
HIDE_draw_arc(void *hid, void *gc, int cx, int cy, int xradius, int yradius, int start_angle, int delta_angle);
HIDE_draw_rect(void *hid, void *gc, int x1, int y1, int x2, int y2);
HIDE_fill_circle(void *hid, void *gc, int cx, int cy, int radius);
HIDE_fill_polygon(void *hid, void *gc, int n_coords, int *x, int *y);
HIDE_fill_rect(void *hid, void *gc, int x1, int y1, int x2, int y2);
HIDE_use_mask(void *hid, int use_it); [TODO]