# 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:

1. envelope events to set up exporting
2. many draw events to actually export the objects
3. 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]