src/hid.h

   1 #ifndef PCB_HID_H
   2 #define PCB_HID_H
   3
   4 #include <stdarg.h>
   5
   6 /* Human Interface Device */
   7
   8 /*
   9
  10 The way the HID layer works is that you instantiate a HID device
  11 structure, and invoke functions through its members.  Code in the
  12 common part of PCB may *not* rely on *anything* other than what's
  13 defined in this file.  Code in the HID layers *may* rely on data and
  14 functions in the common code (like, board size and such) but it's
  15 considered bad form to do so when not needed.
  16
  17 Coordinates are ALWAYS in pcb's default resolution (1/100 mil at the
  18 moment).  Positive X is right, positive Y is down.  Angles are
  19 degrees, with 0 being right (positive X) and 90 being up (negative Y).
  20 All zoom, scaling, panning, and conversions are hidden inside the HID
  21 layers.
  22
  23 The main structure is at the end of this file.
  24
  25 Data structures passed to the HIDs will be copied if the HID needs to
  26 save them.  Data structures retured from the HIDs must not be freed,
  27 and may be changed by the HID in response to new information.
  28
  29 */
  30
  31 #if defined(__cplusplus) && __cplusplus
  32 extern "C"
  33 {
  34 #endif
  35
  36 /* Like end cap styles.  The cap *always* extends beyond the
  37    coordinates given, by half the width of the line.  Beveled ends can
  38    used to make octagonal pads by giving the same x,y coordinate
  39    twice.  */
  40   typedef enum
  41   {
  42     Trace_Cap,                  /* This means we're drawing a trace, which has round caps.  */
  43     Square_Cap,                 /* Square pins or pads. */
  44     Round_Cap,                  /* Round pins or round-ended pads, thermals.  */
  45     Beveled_Cap                 /* Octagon pins or bevel-cornered pads.  */
  46   } EndCapStyle;
  47
  48 /* The HID may need something more than an "int" for colors, timers,
  49    etc.  So it passes/returns one of these, which is castable to a
  50    variety of things.  */
  51   typedef union
  52   {
  53     long lval;
  54     void *ptr;
  55   } hidval;
  56
  57 /* This graphics context is an opaque pointer defined by the HID.  GCs
  58    are HID-specific; attempts to use one HID's GC for a different HID
  59    will result in a fatal error.  */
  60   typedef struct hid_gc_struct *hidGC;
  61
  62 #define HIDCONCAT(a,b) a##b
  63
  64 /* This is used to register the action callbacks (for menus and
  65    whatnot).  HID assumes the following actions are available for its
  66    use:
  67         SaveAs(filename);
  68         Quit();
  69 */
  70   typedef struct
  71   {
  72     /* This is matched against action names in the GUI configuration */
  73     char *name;
  74     /* If this string is non-NULL, the action needs to know the X,Y
  75        coordinates to act on, and this string may be used to prompt
  76        the user to select a coordinate.  If NULL, the coordinates may
  77        be 0,0 if none are known.  */
  78     const char *need_coord_msg;
  79     /* Called when the action is triggered.  If this function returns
  80        non-zero, no further actions will be invoked for this key/mouse
  81        event.  */
  82     int (*trigger_cb) (int argc, char **argv, Coord x, Coord y);
  83     /* Short description that sometimes accompanies the name.  */
  84     const char *description;
  85     /* Full allowed syntax; use \n to separate lines.  */
  86     const char *syntax;
  87   } HID_Action;
  88
  89   extern void hid_register_action (HID_Action *);
  90
  91   extern void hid_register_actions (HID_Action *, int);
  92 #define REGISTER_ACTIONS(a) HIDCONCAT(void register_,a) ()\
  93 { hid_register_actions(a, sizeof(a)/sizeof(a[0])); }
  94
  95   /* Note that PCB expects the gui to provide the following actions:
  96
  97      PCBChanged();
  98      RouteStylesChanged()
  99      NetlistChanged()  (but core should call "void NetlistChanged(int);" in netlist.c)
 100      LayersChanged()
 101      LibraryChanged()
 102      Busy()
 103    */
 104
 105   extern const char pcbchanged_help[];
 106   extern const char pcbchanged_syntax[];
 107   extern const char routestyleschanged_help[];
 108   extern const char routestyleschanged_syntax[];
 109   extern const char netlistchanged_help[];
 110   extern const char netlistchanged_syntax[];
 111   extern const char layerschanged_help[];
 112   extern const char layerschanged_syntax[];
 113   extern const char librarychanged_help[];
 114   extern const char librarychanged_syntax[];
 115
 116   int hid_action (const char *action_);
 117   int hid_actionl (const char *action_, ...);   /* NULL terminated */
 118   int hid_actionv (const char *action_, int argc_, char **argv_);
 119   void hid_save_settings (int);
 120   void hid_load_settings (void);
 121
 122 /* Parse the given command string into action calls, and call
 123    hid_actionv for each action found.  Accepts both "action(arg1,
 124    arg2)" and command-style "action arg1 arg2", allowing only one
 125    action in the later case.  Returns nonzero if the action handler(s)
 126    return nonzero. */
 127   int hid_parse_command (const char *str_);
 128
 129 /* Parse the given string into action calls, and call
 130    hid_actionv for each action found.  Accepts only
 131    "action(arg1, arg2)" */
 132   int hid_parse_actions (const char *str_);
 133
 134   typedef struct
 135   {
 136     /* Name of the flag */
 137     char *name;
 138     /* Function to call to get the value of the flag.  */
 139     int (*function) (void *);
 140     /* Additional parameter to pass to that function.  */
 141     void *parm;
 142   } HID_Flag;
 143
 144   extern void hid_register_flags (HID_Flag *, int);
 145 #define REGISTER_FLAGS(a) HIDCONCAT(void register_,a) ()\
 146 { hid_register_flags(a, sizeof(a)/sizeof(a[0])); }
 147
 148 /* Looks up one of the flags registered above.  If the flag is
 149    unknown, returns zero.  */
 150   int hid_get_flag (const char *name_);
 151
 152 /* Used for HID attributes (exporting and printing, mostly).
 153    HA_boolean uses int_value, HA_enum sets int_value to the index and
 154    str_value to the enumeration string.  HID_Label just shows the
 155    default str_value.  HID_Mixed is a real_value followed by an enum,
 156    like 0.5in or 100mm. */
 157   typedef struct
 158   {
 159     int int_value;
 160     const char *str_value;
 161     double real_value;
 162     Coord coord_value;
 163   } HID_Attr_Val;
 164
 165   enum hids
 166     { HID_Label, HID_Integer, HID_Real, HID_String,
 167       HID_Boolean, HID_Enum, HID_Mixed, HID_Path,
 168       HID_Unit, HID_Coord
 169     };
 170
 171   typedef struct
 172   {
 173     char *name;
 174     /* If the help_text is this, usage() won't show this option */
 175 #define ATTR_UNDOCUMENTED ((char *)(1))
 176     char *help_text;
 177     enum hids type;
 178     int min_val, max_val;       /* for integer and real */
 179     HID_Attr_Val default_val;   /* Also actual value for global attributes.  */
 180     const char **enumerations;
 181     /* If set, this is used for global attributes (i.e. those set
 182        statically with REGISTER_ATTRIBUTES below) instead of changing
 183        the default_val.  Note that a HID_Mixed attribute must specify a
 184        pointer to HID_Attr_Val here, and HID_Boolean assumes this is
 185        "char *" so the value should be initialized to zero, and may be
 186        set to non-zero (not always one).  */
 187     void *value;
 188     int hash; /* for detecting changes. */
 189   } HID_Attribute;
 190
 191   extern void hid_register_attributes (HID_Attribute *, int);
 192 #define REGISTER_ATTRIBUTES(a) HIDCONCAT(void register_,a) ()\
 193 { hid_register_attributes(a, sizeof(a)/sizeof(a[0])); }
 194
 195 /* These three are set by hid_parse_command_line().  */
 196   extern char *program_name;
 197   extern char *program_directory;
 198   extern char *program_basename;
 199
 200 #define SL_0_SIDE       0x0000
 201 #define SL_TOP_SIDE     0x0001
 202 #define SL_BOTTOM_SIDE  0x0002
 203 #define SL_SILK         0x0010
 204 #define SL_MASK         0x0020
 205 #define SL_PDRILL       0x0030
 206 #define SL_UDRILL       0x0040
 207 #define SL_PASTE        0x0050
 208 #define SL_INVISIBLE    0x0060
 209 #define SL_FAB          0x0070
 210 #define SL_ASSY         0x0080
 211 #define SL_RATS         0x0090
 212 /* Callers should use this.  */
 213 #define SL(type,side) (~0xfff | SL_##type | SL_##side##_SIDE)
 214
 215 /* File Watch flags */
 216 /* Based upon those in dbus/dbus-connection.h */
 217 typedef enum
 218 {
 219   PCB_WATCH_READABLE = 1 << 0, /**< As in POLLIN */
 220   PCB_WATCH_WRITABLE = 1 << 1, /**< As in POLLOUT */
 221   PCB_WATCH_ERROR    = 1 << 2, /**< As in POLLERR */
 222   PCB_WATCH_HANGUP   = 1 << 3  /**< As in POLLHUP */
 223 } PCBWatchFlags;
 224
 225 /* DRC GUI Hooks */
 226   typedef struct
 227   {
 228     int log_drc_overview;
 229     int log_drc_violations;
 230     void (*reset_drc_dialog_message) (void);
 231     void (*append_drc_violation) (DrcViolationType *violation);
 232     int (*throw_drc_dialog) (void);
 233   } HID_DRC_GUI;
 234
 235   enum mask_mode {
 236     HID_MASK_OFF    = 0, /* Flush the buffer and return to non-mask operation. */
 237     HID_MASK_BEFORE = 1, /* Polygons being drawn before clears.                */
 238     HID_MASK_CLEAR  = 2, /* Clearances being drawn.                            */
 239     HID_MASK_AFTER  = 3, /* Polygons being drawn after clears.                 */
 240   };
 241
 242   typedef struct hid_st HID;
 243
 244 /* This is the main HID structure.  */
 245   struct hid_st
 246   {
 247     /* The size of this structure.  We use this as a compatibility
 248        check; a HID built with a different hid.h than we're expecting
 249        should have a different size here.  */
 250     int struct_size;
 251
 252     /* The name of this HID.  This should be suitable for
 253        command line options, multi-selection menus, file names,
 254        etc. */
 255     const char *name;
 256
 257     /* Likewise, but allowed to be longer and more descriptive.  */
 258     const char *description;
 259
 260     /* If set, this is the GUI HID.  Exactly one of these three flags
 261        must be set; setting "gui" lets the expose callback optimize and
 262        coordinate itself.  */
 263     char gui:1;
 264
 265     /* If set, this is the printer-class HID.  The common part of PCB
 266        may use this to do command-line printing, without having
 267        instantiated any GUI HIDs.  Only one printer HID is normally
 268        defined at a time.  */
 269     char printer:1;
 270
 271     /* If set, this HID provides an export option, and should be used as
 272        part of the File->Export menu option.  Examples are PNG, Gerber,
 273        and EPS exporters.  */
 274     char exporter:1;
 275
 276     /* If set, the redraw code will draw polygons before erasing the
 277        clearances.  */
 278     char poly_before:1;
 279
 280     /* If set, the redraw code will draw polygons after erasing the
 281        clearances.  Note that HIDs may set both of these, in which case
 282        polygons will be drawn twice.  */
 283     char poly_after:1;
 284
 285     /* Returns a set of resources describing options the export or print
 286        HID supports.  In GUI mode, the print/export dialogs use this to
 287        set up the selectable options.  In command line mode, these are
 288        used to interpret command line options.  If n_ret is non-NULL,
 289        the number of attributes is stored there.  */
 290     HID_Attribute *(*get_export_options) (int *n_ret_);
 291
 292     /* Export (or print) the current PCB.  The options given represent
 293        the choices made from the options returned from
 294        get_export_options.  Call with options == NULL to start the
 295        primary GUI (create a main window, print, export, etc)  */
 296     void (*do_export) (HID_Attr_Val * options_);
 297
 298     /* Parse the command line.  Call this early for whatever HID will be
 299        the primary HID, as it will set all the registered attributes.
 300        The HID should remove all arguments, leaving any possible file
 301        names behind.  */
 302     void (*parse_arguments) (int *argc_, char ***argv_);
 303
 304     /* This may be called to ask the GUI to force a redraw of a given area */
 305     void (*invalidate_lr) (int left_, int right_, int top_, int bottom_);
 306     void (*invalidate_all) (void);
 307     void (*notify_crosshair_change) (bool changes_complete);
 308     void (*notify_mark_change) (bool changes_complete);
 309
 310     /* During redraw or print/export cycles, this is called once per
 311        layer (or layer group, for copper layers).  If it returns false
 312        (zero), the HID does not want that layer, and none of the drawing
 313        functions should be called.  If it returns true (nonzero), the
 314        items in that layer [group] should be drawn using the various
 315        drawing functions.  In addition to the MAX_LAYERS copper layer
 316        groups, you may select layers indicated by the macros SL_*
 317        defined above, or any others with an index of -1.  For copper
 318        layer groups, you may pass NULL for name to have a name fetched
 319        from the PCB struct.  The EMPTY argument is a hint - if set, the
 320        layer is empty, if zero it may be non-empty.  */
 321     int (*set_layer) (const char *name_, int group_, int _empty);
 322
 323     /* Tell the GUI the layer last selected has been finished with */
 324     void (*end_layer) (void);
 325
 326     /* Drawing Functions.  Coordinates and distances are ALWAYS in PCB's
 327        default coordinates (1/100 mil at the time this comment was
 328        written).  Angles are always in degrees, with 0 being "right"
 329        (positive X) and 90 being "up" (positive Y).  */
 330
 331     /* Make an empty graphics context.  */
 332       hidGC (*make_gc) (void);
 333     void (*destroy_gc) (hidGC gc_);
 334
 335     /* Special note about the "erase" color: To use this color, you must
 336        use this function to tell the HID when you're using it.  At the
 337        beginning of a layer redraw cycle (i.e. after set_layer), call
 338        use_mask() to redirect output to a buffer.  Draw to the buffer
 339        (using regular HID calls) using regular and "erase" colors.  Then
 340        call use_mask(HID_MASK_OFF) to flush the buffer to the HID.  If
 341        you use the "erase" color when use_mask is disabled, it simply
 342        draws in the background color.  */
 343     void (*use_mask) (enum mask_mode mode);
 344
 345     /* Set a color.  Names can be like "red" or "#rrggbb" or special
 346        names like "erase".  *Always* use the "erase" color for removing
 347        ink (like polygon reliefs or thermals), as you cannot rely on
 348        knowing the background color or special needs of the HID.  Always
 349        use the "drill" color to draw holes.  You may assume this is
 350        cheap enough to call inside the redraw callback, but not cheap
 351        enough to call for each item drawn. */
 352     void (*set_color) (hidGC gc_, const char *name_);
 353
 354     /* Set the line style.  While calling this is cheap, calling it with
 355        different values each time may be expensive, so grouping items by
 356        line style is helpful.  */
 357     void (*set_line_cap) (hidGC gc_, EndCapStyle style_);
 358     void (*set_line_width) (hidGC gc_, Coord width_);
 359     void (*set_draw_xor) (hidGC gc_, int xor_);
 360     /* Blends 20% or so color with 80% background.  Only used for
 361        assembly drawings so far. */
 362     void (*set_draw_faded) (hidGC gc_, int faded_);
 363
 364     /* The usual drawing functions.  "draw" means to use segments of the
 365        given width, whereas "fill" means to fill to a zero-width
 366        outline.  */
 367     void (*draw_line) (hidGC gc_, Coord x1_, Coord y1_, Coord x2_, Coord y2_);
 368     void (*draw_arc) (hidGC gc_, Coord cx_, Coord cy_, Coord xradius_, Coord yradius_,
 369                       Angle start_angle_, Angle delta_angle_);
 370     void (*draw_rect) (hidGC gc_, Coord x1_, Coord y1_, Coord x2_, Coord y2_);
 371     void (*fill_circle) (hidGC gc_, Coord cx_, Coord cy_, Coord radius_);
 372     void (*fill_polygon) (hidGC gc_, int n_coords_, Coord *x_, Coord *y_);
 373     void (*fill_pcb_polygon) (hidGC gc_, PolygonType *poly,
 374                               const BoxType *clip_box);
 375     void (*thindraw_pcb_polygon) (hidGC gc_, PolygonType *poly,
 376                                   const BoxType *clip_box);
 377     void (*fill_pcb_pad) (hidGC gc_, PadType *pad, bool clip, bool mask);
 378     void (*thindraw_pcb_pad) (hidGC gc_, PadType *pad, bool clip, bool mask);
 379     void (*fill_pcb_pv) (hidGC fg_gc, hidGC bg_gc, PinType *pv, bool drawHole, bool mask);
 380     void (*thindraw_pcb_pv) (hidGC fg_gc, hidGC bg_gc, PinType *pv, bool drawHole, bool mask);
 381     void (*fill_rect) (hidGC gc_, Coord x1_, Coord y1_, Coord x2_, Coord y2_);
 382
 383
 384     /* This is for the printer.  If you call this for the GUI, xval and
 385        yval are ignored, and a dialog pops up to lead you through the
 386        calibration procedure.  For the printer, if xval and yval are
 387        zero, a calibration page is printed with instructions for
 388        calibrating your printer.  After calibrating, nonzero xval and
 389        yval are passed according to the instructions.  Metric is nonzero
 390        if the user prefers metric units, else inches are used. */
 391     void (*calibrate) (double xval_, double yval_);
 392
 393
 394     /* GUI layout functions.  Not used or defined for print/export
 395        HIDs.  */
 396
 397     /* Temporary */
 398     int (*shift_is_pressed) (void);
 399     int (*control_is_pressed) (void);
 400     int (*mod1_is_pressed) (void);
 401     void (*get_coords) (const char *msg_, Coord *x_, Coord *y_);
 402
 403     /* Sets the crosshair, which may differ from the pointer depending
 404        on grid and pad snap.  Note that the HID is responsible for
 405        hiding, showing, redrawing, etc.  The core just tells it what
 406        coordinates it's actually using.  Note that this routine may
 407        need to know what "pcb units" are so it can display them in mm
 408        or mils accordingly.  If cursor_action is set, the cursor or
 409        screen may be adjusted so that the cursor and the crosshair are
 410        at the same point on the screen.  */
 411     void (*set_crosshair) (int x_, int y_, int cursor_action_);
 412 #define HID_SC_DO_NOTHING       0
 413 #define HID_SC_WARP_POINTER     1
 414 #define HID_SC_PAN_VIEWPORT     2
 415
 416     /* Causes func to be called at some point in the future.  Timers are
 417        only good for *one* call; if you want it to repeat, add another
 418        timer during the callback for the first.  user_data can be
 419        anything, it's just passed to func.  Times are not guaranteed to
 420        be accurate.  */
 421       hidval (*add_timer) (void (*func) (hidval user_data_),
 422                            unsigned long milliseconds_, hidval user_data_);
 423     /* Use this to stop a timer that hasn't triggered yet.  */
 424     void (*stop_timer) (hidval timer_);
 425
 426     /* Causes func to be called when some condition occurs on the file
 427        descriptor passed. Conditions include data for reading, writing,
 428        hangup, and errors. user_data can be anything, it's just passed
 429        to func. */
 430       hidval (*watch_file) (int fd_, unsigned int condition_, void (*func_) (hidval watch_, int fd_, unsigned int condition_, hidval user_data_),
 431         hidval user_data);
 432     /* Use this to stop a file watch. */
 433     void (*unwatch_file) (hidval watch_);
 434
 435     /* Causes func to be called in the mainloop prior to blocking */
 436       hidval (*add_block_hook) (void (*func_) (hidval data_), hidval data_);
 437     /* Use this to stop a mainloop block hook. */
 438     void (*stop_block_hook) (hidval block_hook_);
 439
 440     /* Various dialogs */
 441
 442     /* Log a message to the log window.  */
 443     void (*log) (const char *fmt_, ...);
 444     void (*logv) (const char *fmt_, va_list args_);
 445
 446     /* A generic yes/no dialog.  Returns zero if the cancel button is
 447        pressed, one for the ok button.  If you specify alternate labels
 448        for ..., they are used instead of the default OK/Cancel ones, and
 449        the return value is the index of the label chosen.  You MUST pass
 450        NULL as the last parameter to this.  */
 451     int (*confirm_dialog) (char *msg_, ...);
 452
 453     /* A close confirmation dialog for unsaved pages, for example, with
 454        options "Close without saving", "Cancel" and "Save". Returns zero
 455        if the close is cancelled, or one if it should proceed. The HID
 456        is responsible for any "Save" action the user may wish before
 457        confirming the close.
 458        */
 459     int (*close_confirm_dialog) ();
 460 #define HID_CLOSE_CONFIRM_CANCEL 0
 461 #define HID_CLOSE_CONFIRM_OK     1
 462
 463     /* Just prints text.  */
 464     void (*report_dialog) (char *title_, char *msg_);
 465
 466     /* Prompts the user to enter a string, returns the string.  If
 467        default_string isn't NULL, the form is pre-filled with this
 468        value.  "msg" is like "Enter value:".  */
 469     char *(*prompt_for) (const char *msg_, const char *default_string_);
 470
 471     /* Prompts the user for a filename or directory name.  For GUI
 472        HID's this would mean a file select dialog box.  The 'flags'
 473        argument is the bitwise OR of the following values.  */
 474 #define HID_FILESELECT_READ  0x01
 475
 476     /* The function calling hid->fileselect will deal with the case
 477        where the selected file already exists.  If not given, then the
 478        gui will prompt with an "overwrite?" prompt.  Only used when
 479        writing.
 480     */
 481 #define HID_FILESELECT_MAY_NOT_EXIST 0x02
 482
 483     /* The call is supposed to return a file template (for gerber
 484        output for example) instead of an actual file.  Only used when
 485        writing.
 486     */
 487 #define HID_FILESELECT_IS_TEMPLATE 0x04
 488
 489     /* title may be used as a dialog box title.  Ignored if NULL.
 490      *
 491      * descr is a longer help string.  Ignored if NULL.
 492      *
 493      * default_file is the default file name.  Ignored if NULL.
 494      *
 495      * default_ext is the default file extension, like ".pdf".
 496      * Ignored if NULL.
 497      *
 498      * history_tag may be used by the GUI to keep track of file
 499      * history.  Examples would be "board", "vendor", "renumber",
 500      * etc.  If NULL, no specific history is kept.
 501      *
 502      * flags are the bitwise or of the HID_FILESELECT defines above
 503      */
 504
 505     char *(*fileselect) (const char *title_, const char *descr_,
 506                          char *default_file_, char *default_ext_,
 507                          const char *history_tag_, int flags_);
 508
 509     /* A generic dialog to ask for a set of attributes.  If n_attrs is
 510        zero, attrs(.name) must be NULL terminated.  Returns non-zero if
 511        an error occurred (usually, this means the user cancelled the
 512        dialog or something). title is the title of the dialog box
 513        descr (if not NULL) can be a longer description of what the
 514        attributes are used for.  The HID may choose to ignore it or it
 515        may use it for a tooltip or text in a dialog box, or a help
 516        string.
 517     */
 518     int (*attribute_dialog) (HID_Attribute * attrs_,
 519                              int n_attrs_, HID_Attr_Val * results_,
 520                              const char * title_, const char * descr_);
 521
 522     /* This causes a second window to display, which only shows the
 523        selected item. The expose callback is called twice; once to size
 524        the extents of the item, and once to draw it.  To pass magic
 525        values, pass the address of a variable created for this
 526        purpose.  */
 527     void (*show_item) (void *item_);
 528
 529     /* Something to alert the user.  */
 530     void (*beep) (void);
 531
 532     /* Used by optimizers and autorouter to show progress to the user.
 533        Pass all zeros to flush display and remove any dialogs.
 534        Returns nonzero if the user wishes to cancel the operation.  */
 535     int (*progress) (int so_far_, int total_, const char *message_);
 536
 537     HID_DRC_GUI *drc_gui;
 538
 539     void (*edit_attributes) (char *owner, AttributeListType *attrlist_);
 540
 541     /* Debug drawing support. These APIs must be implemented (non NULL),
 542      * but they do not have to be functional. request_debug_draw can
 543      * return NULL to indicate debug drawing is not permitted.
 544      *
 545      * Debug drawing is not gauranteed to be re-entrant.
 546      * The caller must not nest requests for debug drawing.
 547      */
 548
 549     /* Request permission for debug drawing
 550      *
 551      * Returns a HID pointer which should be used rather than the global
 552      * gui-> for making drawing calls. If the return value is NULL, then
 553      * permission has been denied, and the drawing must not continue.
 554      */
 555     HID *(*request_debug_draw) (void);
 556
 557     /* Flush pending drawing to the screen
 558      *
 559      * May be implemented as a NOOP if the GUI has chosen to send the
 560      * debug drawing directly to the screen.
 561      */
 562     void (*flush_debug_draw)   (void);
 563
 564     /* When finished, the user must inform the GUI to clean up resources
 565      *
 566      * Any remaining rendering will be flushed to the screen.
 567      */
 568     void (*finish_debug_draw)  (void);
 569
 570     /* Notification to the GUI around saving the PCB file.
 571      *
 572      * Called with a false parameter before the save, called again
 573      * with true after the save.
 574      *
 575      * Allows GUIs which watch for file-changes on disk to ignore
 576      * our deliberate changes.
 577      */
 578     void (*notify_save_pcb) (const char *filename, bool done);
 579
 580     /* Notification to the GUI that the PCB file has been renamed. */
 581     void (*notify_filename_changed) (void);
 582   };
 583
 584 /* Call this as soon as possible from main().  No other HID calls are
 585    valid until this is called.  */
 586   void hid_init (void);
 587
 588 /* When PCB runs in interactive mode, this is called to instantiate
 589    one GUI HID which happens to be the GUI.  This HID is the one that
 590    interacts with the mouse and keyboard.  */
 591   HID *hid_find_gui ();
 592
 593 /* Finds the one printer HID and instantiates it.  */
 594   HID *hid_find_printer (void);
 595
 596 /* Finds the indicated exporter HID and instantiates it.  */
 597   HID *hid_find_exporter (const char *);
 598
 599 /* This returns a NULL-terminated array of available HIDs.  The only
 600    real reason to use this is to locate all the export-style HIDs. */
 601   HID **hid_enumerate (void);
 602
 603 /* This function (in the common code) will be called whenever the GUI
 604    needs to redraw the screen, print the board, or export a layer.  If
 605    item is not NULL, only draw the given item.  Item is only non-NULL
 606    if the HID was created via show_item.
 607
 608    Each time func is called, it should do the following:
 609
 610    * allocate any colors needed, via get_color.
 611
 612    * cycle through the layers, calling set_layer for each layer to be
 613      drawn, and only drawing elements (all or specified) of desired
 614      layers.
 615
 616    Do *not* assume that the hid that is passed is the GUI hid.  This
 617    callback is also used for printing and exporting. */
 618   struct BoxType;
 619   void hid_expose_callback (HID * hid_, struct BoxType *region_, void *item_);
 620
 621 /* This is initially set to a "no-gui" gui, and later reset by
 622    main. hid_expose_callback also temporarily set it for drawing. */
 623   extern HID *gui;
 624
 625 /* This is either NULL or points to the current HID that is being called to
 626         do the exporting. The gui HIDs set and unset this var.*/
 627   extern HID *exporter;
 628
 629 /* This is either NULL or points to the current HID_Action that is being
 630    called. The action launcher sets and unsets this variable. */
 631   extern HID_Action *current_action;
 632
 633 /* The GUI may set this to be approximately the PCB size of a pixel,
 634    to allow for near-misses in selection and changes in drawing items
 635    smaller than a screen pixel.  */
 636   extern int pixel_slop;
 637
 638 #if defined(__cplusplus) && __cplusplus
 639 }
 640 #endif
 641
 642 #endif