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 semi-opaque pointer defined by the HID.
  58    GCs are HID-specific; attempts to use one HID's GC for a different
  59    HID will result in a fatal error. Certain elements are defined in
  60    hid_draw.h are visible for use in draw.c, but the full structure
  61    size may not be determined from that definition. */
  62   typedef struct hid_gc_struct *hidGC;
  63
  64 #define HIDCONCAT(a,b) a##b
  65
  66 /* This is used to register the action callbacks (for menus and
  67    whatnot).  HID assumes the following actions are available for its
  68    use:
  69         SaveAs(filename);
  70         Quit();
  71 */
  72   typedef struct
  73   {
  74     /* This is matched against action names in the GUI configuration */
  75     char *name;
  76     /* If this string is non-NULL, the action needs to know the X,Y
  77        coordinates to act on, and this string may be used to prompt
  78        the user to select a coordinate.  If NULL, the coordinates may
  79        be 0,0 if none are known.  */
  80     const char *need_coord_msg;
  81     /* Called when the action is triggered.  If this function returns
  82        non-zero, no further actions will be invoked for this key/mouse
  83        event.  */
  84     int (*trigger_cb) (int argc, char **argv, Coord x, Coord y);
  85     /* Short description that sometimes accompanies the name.  */
  86     const char *description;
  87     /* Full allowed syntax; use \n to separate lines.  */
  88     const char *syntax;
  89   } HID_Action;
  90
  91   extern void hid_register_action (HID_Action *);
  92
  93   extern void hid_register_actions (HID_Action *, int);
  94 #define REGISTER_ACTIONS(a) HIDCONCAT(void register_,a) ()\
  95 { hid_register_actions(a, sizeof(a)/sizeof(a[0])); }
  96
  97   /* Note that PCB expects the gui to provide the following actions:
  98
  99      PCBChanged();
 100      RouteStylesChanged()
 101      NetlistChanged()  (but core should call "void NetlistChanged(int);" in netlist.c)
 102      LayersChanged()
 103      LibraryChanged()
 104      Busy()
 105    */
 106
 107   extern const char pcbchanged_help[];
 108   extern const char pcbchanged_syntax[];
 109   extern const char routestyleschanged_help[];
 110   extern const char routestyleschanged_syntax[];
 111   extern const char netlistchanged_help[];
 112   extern const char netlistchanged_syntax[];
 113   extern const char layerschanged_help[];
 114   extern const char layerschanged_syntax[];
 115   extern const char librarychanged_help[];
 116   extern const char librarychanged_syntax[];
 117
 118   int hid_action (const char *action_);
 119   int hid_actionl (const char *action_, ...);   /* NULL terminated */
 120   int hid_actionv (const char *action_, int argc_, char **argv_);
 121   void hid_save_settings (int);
 122   void hid_load_settings (void);
 123
 124 /* Parse the given command string into action calls, and call
 125    hid_actionv for each action found.  Accepts both "action(arg1,
 126    arg2)" and command-style "action arg1 arg2", allowing only one
 127    action in the later case.  Returns nonzero if the action handler(s)
 128    return nonzero. */
 129   int hid_parse_command (const char *str_);
 130
 131 /* Parse the given string into action calls, and call
 132    hid_actionv for each action found.  Accepts only
 133    "action(arg1, arg2)" */
 134   int hid_parse_actions (const char *str_);
 135
 136   typedef struct
 137   {
 138     /* Name of the flag */
 139     char *name;
 140     /* Function to call to get the value of the flag.  */
 141     int (*function) (void *);
 142     /* Additional parameter to pass to that function.  */
 143     void *parm;
 144   } HID_Flag;
 145
 146   extern void hid_register_flags (HID_Flag *, int);
 147 #define REGISTER_FLAGS(a) HIDCONCAT(void register_,a) ()\
 148 { hid_register_flags(a, sizeof(a)/sizeof(a[0])); }
 149
 150 /* Looks up one of the flags registered above.  If the flag is
 151    unknown, returns zero.  */
 152   int hid_get_flag (const char *name_);
 153
 154 /* Used for HID attributes (exporting and printing, mostly).
 155    HA_boolean uses int_value, HA_enum sets int_value to the index and
 156    str_value to the enumeration string.  HID_Label just shows the
 157    default str_value.  HID_Mixed is a real_value followed by an enum,
 158    like 0.5in or 100mm. */
 159   typedef struct
 160   {
 161     int int_value;
 162     const char *str_value;
 163     double real_value;
 164     Coord coord_value;
 165   } HID_Attr_Val;
 166
 167   enum hids
 168     { HID_Label, HID_Integer, HID_Real, HID_String,
 169       HID_Boolean, HID_Enum, HID_Mixed, HID_Path,
 170       HID_Unit, HID_Coord
 171     };
 172
 173   typedef struct
 174   {
 175     char *name;
 176     /* If the help_text is this, usage() won't show this option */
 177 #define ATTR_UNDOCUMENTED ((char *)(1))
 178     char *help_text;
 179     enum hids type;
 180     int min_val, max_val;       /* for integer and real */
 181     HID_Attr_Val default_val;   /* Also actual value for global attributes.  */
 182     const char **enumerations;
 183     /* If set, this is used for global attributes (i.e. those set
 184        statically with REGISTER_ATTRIBUTES below) instead of changing
 185        the default_val.  Note that a HID_Mixed attribute must specify a
 186        pointer to HID_Attr_Val here, and HID_Boolean assumes this is
 187        "char *" so the value should be initialized to zero, and may be
 188        set to non-zero (not always one).  */
 189     void *value;
 190     int hash; /* for detecting changes. */
 191   } HID_Attribute;
 192
 193   extern void hid_register_attributes (HID_Attribute *, int);
 194 #define REGISTER_ATTRIBUTES(a) HIDCONCAT(void register_,a) ()\
 195 { hid_register_attributes(a, sizeof(a)/sizeof(a[0])); }
 196
 197 /* These three are set by hid_parse_command_line().  */
 198   extern char *program_name;
 199   extern char *program_directory;
 200   extern char *program_basename;
 201
 202 #define SL_0_SIDE       0x0000
 203 #define SL_TOP_SIDE     0x0001
 204 #define SL_BOTTOM_SIDE  0x0002
 205 #define SL_SILK         0x0010
 206 #define SL_MASK         0x0020
 207 #define SL_PDRILL       0x0030
 208 #define SL_UDRILL       0x0040
 209 #define SL_PASTE        0x0050
 210 #define SL_INVISIBLE    0x0060
 211 #define SL_FAB          0x0070
 212 #define SL_ASSY         0x0080
 213 #define SL_RATS         0x0090
 214 /* Callers should use this.  */
 215 #define SL(type,side) (~0xfff | SL_##type | SL_##side##_SIDE)
 216
 217 /* File Watch flags */
 218 /* Based upon those in dbus/dbus-connection.h */
 219 typedef enum
 220 {
 221   PCB_WATCH_READABLE = 1 << 0, /**< As in POLLIN */
 222   PCB_WATCH_WRITABLE = 1 << 1, /**< As in POLLOUT */
 223   PCB_WATCH_ERROR    = 1 << 2, /**< As in POLLERR */
 224   PCB_WATCH_HANGUP   = 1 << 3  /**< As in POLLHUP */
 225 } PCBWatchFlags;
 226
 227 /* DRC GUI Hooks */
 228   typedef struct
 229   {
 230     int log_drc_overview;
 231     int log_drc_violations;
 232     void (*reset_drc_dialog_message) (void);
 233     void (*append_drc_violation) (DrcViolationType *violation);
 234     int (*throw_drc_dialog) (void);
 235   } HID_DRC_GUI;
 236
 237   typedef struct hid_st HID;
 238   typedef struct hid_draw_st HID_DRAW;
 239
 240 /* This is the main HID structure.  */
 241   struct hid_st
 242   {
 243     /* The size of this structure.  We use this as a compatibility
 244        check; a HID built with a different hid.h than we're expecting
 245        should have a different size here.  */
 246     int struct_size;
 247
 248     /* The name of this HID.  This should be suitable for
 249        command line options, multi-selection menus, file names,
 250        etc. */
 251     const char *name;
 252
 253     /* Likewise, but allowed to be longer and more descriptive.  */
 254     const char *description;
 255
 256     /* If set, this is the GUI HID.  Exactly one of these three flags
 257        must be set; setting "gui" lets the expose callback optimize and
 258        coordinate itself.  */
 259     char gui:1;
 260
 261     /* If set, this is the printer-class HID.  The common part of PCB
 262        may use this to do command-line printing, without having
 263        instantiated any GUI HIDs.  Only one printer HID is normally
 264        defined at a time.  */
 265     char printer:1;
 266
 267     /* If set, this HID provides an export option, and should be used as
 268        part of the File->Export menu option.  Examples are PNG, Gerber,
 269        and EPS exporters.  */
 270     char exporter:1;
 271
 272     /* Returns a set of resources describing options the export or print
 273        HID supports.  In GUI mode, the print/export dialogs use this to
 274        set up the selectable options.  In command line mode, these are
 275        used to interpret command line options.  If n_ret is non-NULL,
 276        the number of attributes is stored there.  */
 277     HID_Attribute *(*get_export_options) (int *n_ret_);
 278
 279     /* Export (or print) the current PCB.  The options given represent
 280        the choices made from the options returned from
 281        get_export_options.  Call with options == NULL to start the
 282        primary GUI (create a main window, print, export, etc)  */
 283     void (*do_export) (HID_Attr_Val * options_);
 284
 285     /* Parse the command line.  Call this early for whatever HID will be
 286        the primary HID, as it will set all the registered attributes.
 287        The HID should remove all arguments, leaving any possible file
 288        names behind.  */
 289     void (*parse_arguments) (int *argc_, char ***argv_);
 290
 291     /* This may be called to ask the GUI to force a redraw of a given area */
 292     void (*invalidate_lr) (int left_, int right_, int top_, int bottom_);
 293     void (*invalidate_all) (void);
 294     void (*notify_crosshair_change) (bool changes_complete);
 295     void (*notify_mark_change) (bool changes_complete);
 296
 297     HID_DRAW *graphics;
 298
 299     /* This is for the printer.  If you call this for the GUI, xval and
 300        yval are ignored, and a dialog pops up to lead you through the
 301        calibration procedure.  For the printer, if xval and yval are
 302        zero, a calibration page is printed with instructions for
 303        calibrating your printer.  After calibrating, nonzero xval and
 304        yval are passed according to the instructions.  Metric is nonzero
 305        if the user prefers metric units, else inches are used. */
 306     void (*calibrate) (double xval_, double yval_);
 307
 308
 309     /* GUI layout functions.  Not used or defined for print/export
 310        HIDs.  */
 311
 312     /* Temporary */
 313     int (*shift_is_pressed) (void);
 314     int (*control_is_pressed) (void);
 315     int (*mod1_is_pressed) (void);
 316     void (*get_coords) (const char *msg_, Coord *x_, Coord *y_);
 317
 318     /* Sets the crosshair, which may differ from the pointer depending
 319        on grid and pad snap.  Note that the HID is responsible for
 320        hiding, showing, redrawing, etc.  The core just tells it what
 321        coordinates it's actually using.  Note that this routine may
 322        need to know what "pcb units" are so it can display them in mm
 323        or mils accordingly.  If cursor_action is set, the cursor or
 324        screen may be adjusted so that the cursor and the crosshair are
 325        at the same point on the screen.  */
 326     void (*set_crosshair) (int x_, int y_, int cursor_action_);
 327 #define HID_SC_DO_NOTHING       0
 328 #define HID_SC_WARP_POINTER     1
 329 #define HID_SC_PAN_VIEWPORT     2
 330
 331     /* Causes func to be called at some point in the future.  Timers are
 332        only good for *one* call; if you want it to repeat, add another
 333        timer during the callback for the first.  user_data can be
 334        anything, it's just passed to func.  Times are not guaranteed to
 335        be accurate.  */
 336       hidval (*add_timer) (void (*func) (hidval user_data_),
 337                            unsigned long milliseconds_, hidval user_data_);
 338     /* Use this to stop a timer that hasn't triggered yet.  */
 339     void (*stop_timer) (hidval timer_);
 340
 341     /* Causes func to be called when some condition occurs on the file
 342        descriptor passed. Conditions include data for reading, writing,
 343        hangup, and errors. user_data can be anything, it's just passed
 344        to func. */
 345       hidval (*watch_file) (int fd_, unsigned int condition_, void (*func_) (hidval watch_, int fd_, unsigned int condition_, hidval user_data_),
 346         hidval user_data);
 347     /* Use this to stop a file watch. */
 348     void (*unwatch_file) (hidval watch_);
 349
 350     /* Causes func to be called in the mainloop prior to blocking */
 351       hidval (*add_block_hook) (void (*func_) (hidval data_), hidval data_);
 352     /* Use this to stop a mainloop block hook. */
 353     void (*stop_block_hook) (hidval block_hook_);
 354
 355     /* Various dialogs */
 356
 357     /* Log a message to the log window.  */
 358     void (*log) (const char *fmt_, ...);
 359     void (*logv) (const char *fmt_, va_list args_);
 360
 361     /* A generic yes/no dialog.  Returns zero if the cancel button is
 362        pressed, one for the ok button.  If you specify alternate labels
 363        for ..., they are used instead of the default OK/Cancel ones, and
 364        the return value is the index of the label chosen.  You MUST pass
 365        NULL as the last parameter to this.  */
 366     int (*confirm_dialog) (char *msg_, ...);
 367
 368     /* A close confirmation dialog for unsaved pages, for example, with
 369        options "Close without saving", "Cancel" and "Save". Returns zero
 370        if the close is cancelled, or one if it should proceed. The HID
 371        is responsible for any "Save" action the user may wish before
 372        confirming the close.
 373        */
 374     int (*close_confirm_dialog) ();
 375 #define HID_CLOSE_CONFIRM_CANCEL 0
 376 #define HID_CLOSE_CONFIRM_OK     1
 377
 378     /* Just prints text.  */
 379     void (*report_dialog) (char *title_, char *msg_);
 380
 381     /* Prompts the user to enter a string, returns the string.  If
 382        default_string isn't NULL, the form is pre-filled with this
 383        value.  "msg" is like "Enter value:".  */
 384     char *(*prompt_for) (const char *msg_, const char *default_string_);
 385
 386     /* Prompts the user for a filename or directory name.  For GUI
 387        HID's this would mean a file select dialog box.  The 'flags'
 388        argument is the bitwise OR of the following values.  */
 389 #define HID_FILESELECT_READ  0x01
 390
 391     /* The function calling hid->fileselect will deal with the case
 392        where the selected file already exists.  If not given, then the
 393        gui will prompt with an "overwrite?" prompt.  Only used when
 394        writing.
 395     */
 396 #define HID_FILESELECT_MAY_NOT_EXIST 0x02
 397
 398     /* The call is supposed to return a file template (for gerber
 399        output for example) instead of an actual file.  Only used when
 400        writing.
 401     */
 402 #define HID_FILESELECT_IS_TEMPLATE 0x04
 403
 404     /* title may be used as a dialog box title.  Ignored if NULL.
 405      *
 406      * descr is a longer help string.  Ignored if NULL.
 407      *
 408      * default_file is the default file name.  Ignored if NULL.
 409      *
 410      * default_ext is the default file extension, like ".pdf".
 411      * Ignored if NULL.
 412      *
 413      * history_tag may be used by the GUI to keep track of file
 414      * history.  Examples would be "board", "vendor", "renumber",
 415      * etc.  If NULL, no specific history is kept.
 416      *
 417      * flags are the bitwise or of the HID_FILESELECT defines above
 418      */
 419
 420     char *(*fileselect) (const char *title_, const char *descr_,
 421                          char *default_file_, char *default_ext_,
 422                          const char *history_tag_, int flags_);
 423
 424     /* A generic dialog to ask for a set of attributes.  If n_attrs is
 425        zero, attrs(.name) must be NULL terminated.  Returns non-zero if
 426        an error occurred (usually, this means the user cancelled the
 427        dialog or something). title is the title of the dialog box
 428        descr (if not NULL) can be a longer description of what the
 429        attributes are used for.  The HID may choose to ignore it or it
 430        may use it for a tooltip or text in a dialog box, or a help
 431        string.
 432     */
 433     int (*attribute_dialog) (HID_Attribute * attrs_,
 434                              int n_attrs_, HID_Attr_Val * results_,
 435                              const char * title_, const char * descr_);
 436
 437     /* This causes a second window to display, which only shows the
 438        selected item. The expose callback is called twice; once to size
 439        the extents of the item, and once to draw it.  To pass magic
 440        values, pass the address of a variable created for this
 441        purpose.  */
 442     void (*show_item) (void *item_);
 443
 444     /* Something to alert the user.  */
 445     void (*beep) (void);
 446
 447     /* Used by optimizers and autorouter to show progress to the user.
 448        Pass all zeros to flush display and remove any dialogs.
 449        Returns nonzero if the user wishes to cancel the operation.  */
 450     int (*progress) (int so_far_, int total_, const char *message_);
 451
 452     HID_DRC_GUI *drc_gui;
 453
 454     void (*edit_attributes) (char *owner, AttributeListType *attrlist_);
 455
 456     /* Debug drawing support. These APIs must be implemented (non NULL),
 457      * but they do not have to be functional. request_debug_draw can
 458      * return NULL to indicate debug drawing is not permitted.
 459      *
 460      * Debug drawing is not gauranteed to be re-entrant.
 461      * The caller must not nest requests for debug drawing.
 462      */
 463
 464     /* Request permission for debug drawing
 465      *
 466      * Returns a HID_DRAW pointer which should be used rather than the global
 467      * gui->graphics-> for making drawing calls. If the return value is NULL,
 468      * then permission has been denied, and the drawing must not continue.
 469      */
 470     HID_DRAW *(*request_debug_draw) (void);
 471
 472     /* Flush pending drawing to the screen
 473      *
 474      * May be implemented as a NOOP if the GUI has chosen to send the
 475      * debug drawing directly to the screen.
 476      */
 477     void (*flush_debug_draw)   (void);
 478
 479     /* When finished, the user must inform the GUI to clean up resources
 480      *
 481      * Any remaining rendering will be flushed to the screen.
 482      */
 483     void (*finish_debug_draw)  (void);
 484
 485     /* Notification to the GUI around saving the PCB file.
 486      *
 487      * Called with a false parameter before the save, called again
 488      * with true after the save.
 489      *
 490      * Allows GUIs which watch for file-changes on disk to ignore
 491      * our deliberate changes.
 492      */
 493     void (*notify_save_pcb) (const char *filename, bool done);
 494
 495     /* Notification to the GUI that the PCB file has been renamed. */
 496     void (*notify_filename_changed) (void);
 497   };
 498
 499 /* Call this as soon as possible from main().  No other HID calls are
 500    valid until this is called.  */
 501   void hid_init (void);
 502
 503 /* When PCB runs in interactive mode, this is called to instantiate
 504    one GUI HID which happens to be the GUI.  This HID is the one that
 505    interacts with the mouse and keyboard.  */
 506   HID *hid_find_gui ();
 507
 508 /* Finds the one printer HID and instantiates it.  */
 509   HID *hid_find_printer (void);
 510
 511 /* Finds the indicated exporter HID and instantiates it.  */
 512   HID *hid_find_exporter (const char *);
 513
 514 /* This returns a NULL-terminated array of available HIDs.  The only
 515    real reason to use this is to locate all the export-style HIDs. */
 516   HID **hid_enumerate (void);
 517
 518 /* This function (in the common code) will be called whenever the GUI
 519    needs to redraw the screen, print the board, or export a layer.  If
 520    item is not NULL, only draw the given item.  Item is only non-NULL
 521    if the HID was created via show_item.
 522
 523    Each time func is called, it should do the following:
 524
 525    * allocate any colors needed, via get_color.
 526
 527    * cycle through the layers, calling set_layer for each layer to be
 528      drawn, and only drawing elements (all or specified) of desired
 529      layers.
 530
 531    Do *not* assume that the hid that is passed is the GUI hid.  This
 532    callback is also used for printing and exporting. */
 533   void hid_expose_callback (HID * hid_, struct BoxType *region_, void *item_);
 534
 535 /* This is initially set to a "no-gui" gui, and later reset by
 536    main. hid_expose_callback also temporarily set it for drawing. */
 537   extern HID *gui;
 538
 539 /* This is either NULL or points to the current HID that is being called to
 540         do the exporting. The gui HIDs set and unset this var.*/
 541   extern HID *exporter;
 542
 543 /* This is either NULL or points to the current HID_Action that is being
 544    called. The action launcher sets and unsets this variable. */
 545   extern HID_Action *current_action;
 546
 547 /* The GUI may set this to be approximately the PCB size of a pixel,
 548    to allow for near-misses in selection and changes in drawing items
 549    smaller than a screen pixel.  */
 550   extern int pixel_slop;
 551
 552 #if defined(__cplusplus) && __cplusplus
 553 }
 554 #endif
 555
 556 #endif