1 /*! 2 * \file src/hid.h 3 * 4 * \brief Human Interface Device. 5 * 6 * \author This file, hid.h, was written and is 7 * Copyright (c) 2006 DJ Delorie <dj@delorie.com> 8 * 9 * The way the HID layer works is that you instantiate a HID device 10 * structure, and invoke functions through its members. 11 * 12 * Code in the common part of PCB may *not* rely on *anything* other 13 * than what's defined in this file. 14 * 15 * Code in the HID layers *may* rely on data and functions in the common 16 * code (like, board size and such) but it's considered bad form to do 17 * so when not needed. 18 * 19 * Coordinates are ALWAYS in pcb's default resolution. 20 * 21 * Positive X is right, positive Y is down. 22 * 23 * Angles are degrees, with 0 being right (positive X) and 90 being up 24 * (negative Y). 25 * 26 * All zoom, scaling, panning, and conversions are hidden inside the HID 27 * layers. 28 * 29 * The main structure is at the end of this file. 30 * 31 * Data structures passed to the HIDs will be copied if the HID needs to 32 * save them. 33 * 34 * Data structures retured from the HIDs must not be freed, and may be 35 * changed by the HID in response to new information. 36 * 37 * <hr> 38 * 39 * <h1><b>Copyright.</b></h1>\n 40 * 41 * PCB, interactive printed circuit board design 42 * 43 * Copyright (C) 1994,1995,1996 Thomas Nau 44 * 45 * Copyright (C) 1998,1999,2000,2001 harry eaton 46 * 47 * This program is free software; you can redistribute it and/or modify 48 * it under the terms of the GNU General Public License as published by 49 * the Free Software Foundation; either version 2 of the License, or 50 * (at your option) any later version. 51 * 52 * This program is distributed in the hope that it will be useful, 53 * but WITHOUT ANY WARRANTY; without even the implied warranty of 54 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 55 * GNU General Public License for more details. 56 * 57 * You should have received a copy of the GNU General Public License along 58 * with this program; if not, write to the Free Software Foundation, Inc., 59 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 60 * 61 * Contact addresses for paper mail and Email: 62 * harry eaton, 6697 Buttonhole Ct, Columbia, MD 21044 USA 63 * haceaton@aplcomm.jhuapl.edu 64 */ 65 66 #ifndef PCB_HID_H 67 #define PCB_HID_H 68 69 #include <stdarg.h> 70 71 #include "drc/drc_violation.h" /* DrcViolationType */ 72 73 #if defined(__cplusplus) && __cplusplus 74 extern "C" 75 { 76 #endif 77 78 /*! 79 * \brief Like end cap styles. 80 * 81 * The cap *always* extends beyond the coordinates given, by half the 82 * width of the line. 83 * 84 * Beveled ends can used to make octagonal pads by giving the same x,y 85 * coordinate twice. 86 */ 87 typedef enum 88 { 89 Trace_Cap, /*!< This means we're drawing a trace, which has round caps. */ 90 Square_Cap, /*!< Square pins or pads. */ 91 Round_Cap, /*!< Round pins or round-ended pads, thermals. */ 92 Beveled_Cap /*!< Octagon pins or bevel-cornered pads. */ 93 } EndCapStyle; 94 95 /*! 96 * \brief The HID may need something more than an "int" for colors, 97 * timers, etc. 98 * 99 * So it passes/returns one of these, which is castable to a variety 100 * of things. 101 */ 102 typedef union 103 { 104 long lval; 105 void *ptr; 106 } hidval; 107 108 /*! 109 * This graphics context is an opaque pointer defined by the HID. 110 * 111 * GCs are HID-specific; attempts to use one HID's GC for a different 112 * HID will result in a fatal error. 113 */ 114 typedef struct hid_gc_struct *hidGC; 115 116 #define HIDCONCAT(a,b) a##b 117 118 /*! 119 * \brief This is used to register the action callbacks (for menus and 120 * whatnot). 121 * 122 * HID assumes the following actions are available for its use: 123 * - SaveAs(filename); 124 * - Quit(); 125 */ 126 typedef struct 127 { 128 char *name; 129 /*!< This is matched against action names in the GUI configuration */ 130 const char *need_coord_msg; 131 /*!< If this string is non-NULL, the action needs to know the X,Y 132 * coordinates to act on, and this string may be used to prompt 133 * the user to select a coordinate. If NULL, the coordinates may 134 * be 0,0 if none are known. */ 135 int (*trigger_cb) (int argc, char **argv, Coord x, Coord y); 136 /*!< Called when the action is triggered. If this function returns 137 * non-zero, no further actions will be invoked for this key/mouse 138 * event. */ 139 const char *description; 140 /*!< Short description that sometimes accompanies the name. */ 141 const char *syntax; 142 /*!< Full allowed syntax; use \\n to separate lines. */ 143 } HID_Action; 144 145 extern void hid_register_action (HID_Action *); 146 147 extern void hid_register_actions (HID_Action *, int); 148 #define REGISTER_ACTIONS(a) HIDCONCAT(void register_,a) ()\ 149 { hid_register_actions(a, sizeof(a)/sizeof(a[0])); } 150 151 /* Note that PCB expects the gui to provide the following actions: 152 153 PCBChanged(); 154 RouteStylesChanged() 155 NetlistChanged() (but core should call "void NetlistChanged(int);" in netlist.c) 156 LayersChanged() 157 LibraryChanged() 158 Busy() 159 */ 160 161 extern const char pcbchanged_help[]; 162 extern const char pcbchanged_syntax[]; 163 extern const char routestyleschanged_help[]; 164 extern const char routestyleschanged_syntax[]; 165 extern const char netlistchanged_help[]; 166 extern const char netlistchanged_syntax[]; 167 extern const char layerschanged_help[]; 168 extern const char layerschanged_syntax[]; 169 extern const char librarychanged_help[]; 170 extern const char librarychanged_syntax[]; 171 172 int hid_action (const char *action_); 173 int hid_actionl (const char *action_, ...); /* NULL terminated */ 174 int hid_actionv (const char *action_, int argc_, char **argv_); 175 void hid_save_settings (int); 176 void hid_load_settings (void); 177 178 /*! 179 * \brief Parse the given command string into action calls, and call 180 * hid_actionv for each action found. 181 * 182 * Accepts both "action(arg1, arg2)" and command-style 183 * "action arg1 arg2", allowing only one action in the later case. 184 * 185 * \return Returns nonzero if the action handler(s) return nonzero. 186 */ 187 int hid_parse_command (const char *str_); 188 189 /*! 190 * \brief Parse the given string into action calls, and call hid_actionv 191 * for each action found. 192 * 193 * Accepts only "action(arg1, arg2)". 194 */ 195 int hid_parse_actions (const char *str_); 196 197 typedef struct 198 { 199 char *name; /*!< Name of the flag */ 200 int (*function) (void *); 201 /*!< Function to call to get the value of the flag. */ 202 void *parm; 203 /*!< Additional parameter to pass to that function. */ 204 } HID_Flag; 205 206 extern void hid_register_flags (HID_Flag *, int); 207 #define REGISTER_FLAGS(a) HIDCONCAT(void register_,a) ()\ 208 { hid_register_flags(a, sizeof(a)/sizeof(a[0])); } 209 210 /*! 211 * \brief Looks up one of the flags registered above. 212 * 213 * \return If the flag is unknown, returns zero. 214 */ 215 int hid_get_flag (const char *name_); 216 217 /*! 218 * \brief Used for HID attributes (exporting and printing, mostly). 219 * 220 * HA_boolean uses int_value, HA_enum sets int_value to the index and 221 * str_value to the enumeration string. 222 * 223 * HID_Label just shows the default str_value. 224 * 225 * HID_Mixed is a real_value followed by an enum, like 0.5in or 100mm. 226 */ 227 typedef struct 228 { 229 int int_value; 230 const char *str_value; 231 double real_value; 232 Coord coord_value; 233 } HID_Attr_Val; 234 235 enum hids 236 { HID_Label, HID_Integer, HID_Real, HID_String, 237 HID_Boolean, HID_Enum, HID_Mixed, HID_Path, 238 HID_Unit, HID_Coord 239 }; 240 241 typedef struct 242 { 243 char *name; 244 #define ATTR_UNDOCUMENTED ((char *)(1)) 245 char *help_text; 246 /*!< If the help_text is this, usage() won't show this option */ 247 enum hids type; 248 int min_val; /*!< For integer and real */ 249 int max_val; /*!< For integer and real */ 250 HID_Attr_Val default_val; /*!< Also actual value for global attributes. */ 251 const char **enumerations; 252 void *value; 253 /*!< If set, this is used for global attributes (i.e. those set 254 * statically with REGISTER_ATTRIBUTES below) instead of changing 255 * the default_val. 256 * \note Note that a HID_Mixed attribute must specify a pointer to 257 * HID_Attr_Val here, and HID_Boolean assumes this is "char *" so 258 * the value should be initialized to zero, and may be set to 259 * non-zero (not always one). 260 */ 261 int hash; /*!< For detecting changes. */ 262 } HID_Attribute; 263 264 extern void hid_register_attributes (HID_Attribute *, int); 265 266 #define REGISTER_ATTRIBUTES(a) HIDCONCAT(void register_,a) ()\ 267 { hid_register_attributes(a, sizeof(a)/sizeof(a[0])); } 268 269 /* These three are set by hid_parse_command_line(). */ 270 extern char *program_name; 271 extern char *program_directory; 272 extern char *program_basename; 273 274 /* These are used for set_layer(). */ 275 #define SL_0_SIDE 0x0000 276 #define SL_TOP_SIDE 0x0001 277 #define SL_BOTTOM_SIDE 0x0002 278 #define SL_INNER_SIDE 0x0004 279 280 /* 281 * These are types of "layers" without direct physical representation. 282 * Their content can be derived from other layers and element data. 283 * 284 * These values are used by DrawEverything() in draw.c to ask the active 285 * GUI or exporter to act on these layers. Depending on the GUI/exporter 286 * they result in a per-layer file, in some additional graphics or just 287 * nothing. 288 */ 289 #define SL_SILK 0x0010 /*!< Physical layer, deprecated, use LT_SILK. */ 290 #define SL_MASK 0x0020 291 #define SL_PDRILL 0x0030 292 #define SL_UDRILL 0x0040 293 #define SL_PASTE 0x0050 294 #define SL_INVISIBLE 0x0060 295 #define SL_FAB 0x0070 296 #define SL_ASSY 0x0080 297 #define SL_RATS 0x0090 298 299 /* Callers should use this. */ 300 #define SL(type,side) (~0xfff | SL_##type | SL_##side##_SIDE) 301 302 /*! 303 * These are layers with direct physical representation, like copper, dye 304 * or to be milled paths. Their data can't be derived from other layers or 305 * element data. 306 * 307 * To add more layer types, add them to the list here and in layerflags.c. 308 * Order of entries in both lists must be the same. 309 */ 310 typedef enum 311 { 312 LT_COPPER = 0, 313 LT_SILK, 314 LT_MASK, /*!< Complements SL_MASK above. */ 315 LT_PASTE, /*!< Complements SL_PASTE above. */ 316 LT_OUTLINE, /*!< Board outline; exists only once. */ 317 LT_ROUTE, 318 LT_KEEPOUT, 319 LT_FAB, /*!< Complements SL_FAB above. */ 320 LT_ASSY, /*!< Complements SL_ASSY above. */ 321 LT_NOTES, 322 LT_NUM_LAYERTYPES /*!< Must be the last one. */ 323 } LayertypeType; 324 325 /*! 326 * \brief File Watch flags. 327 * 328 * Based upon those in dbus/dbus-connection.h. 329 */ 330 typedef enum 331 { 332 PCB_WATCH_READABLE = 1 << 0, /*!< As in POLLIN */ 333 PCB_WATCH_WRITABLE = 1 << 1, /*!< As in POLLOUT */ 334 PCB_WATCH_ERROR = 1 << 2, /*!< As in POLLERR */ 335 PCB_WATCH_HANGUP = 1 << 3 /*!< As in POLLHUP */ 336 } PCBWatchFlags; 337 338 /*! 339 * \brief DRC GUI Hooks. 340 */ 341 typedef struct 342 { 343 int log_drc_overview; 344 int log_drc_violations; 345 void (*reset_drc_dialog_message) (void); 346 void (*append_drc_violation) (DrcViolationType *violation); 347 int (*throw_drc_dialog) (void); 348 } HID_DRC_GUI; 349 350 typedef struct hid_st HID; 351 typedef struct hid_draw_st HID_DRAW; 352 353 /*! 354 * \brief This is the main HID structure. 355 */ 356 struct hid_st 357 { 358 int struct_size; 359 /*!< The size of this structure. 360 * 361 * We use this as a compatibility check; a HID built with a 362 * different hid.h than we're expecting should have a different 363 * size here. 364 */ 365 366 const char *name; 367 /*!< The name of this HID. 368 * 369 * This should be suitable for command line options, 370 * multi-selection menus, file names, etc. 371 */ 372 373 const char *description; 374 /*!< Likewise, but allowed to be longer and more descriptive. */ 375 376 char gui:1; 377 /*!< If set, this is the GUI HID. 378 * 379 * Exactly one of these three flags must be set; setting "gui" 380 * lets the expose callback optimize and coordinate itself. 381 */ 382 383 char printer:1; 384 /*!< If set, this is the printer-class HID. 385 * 386 * The common part of PCB may use this to do command-line printing, 387 * without having instantiated any GUI HIDs. 388 * Only one printer HID is normally defined at a time. 389 */ 390 391 char exporter:1; 392 /*!< If set, this HID provides an export option, and should be 393 * used as part of the File->Export menu option. 394 * 395 * Examples are PNG, Gerber, and EPS exporters. 396 */ 397 398 char poly_before:1; 399 /*!< If set, the redraw code will draw polygons before erasing the 400 * clearances. 401 */ 402 403 char poly_after:1; 404 /*!< If set, the redraw code will draw polygons after erasing the 405 * clearances. 406 * 407 * \note Note that HIDs may set both of these, in which case 408 * polygons will be drawn twice. 409 */ 410 411 HID_Attribute *(*get_export_options) (int *n_ret_); 412 /*!< Returns a set of resources describing options the export or 413 * print HID supports. 414 * 415 * In GUI mode, the print/export dialogs use this to set up the 416 * selectable options. 417 * 418 * In command line mode, these are used to interpret command line 419 * options. 420 * 421 * If \c n_ret_ is non-NULL, the number of attributes is stored 422 * there. 423 */ 424 425 void (*do_export) (HID_Attr_Val * options_); 426 /*!< Export (or print) the current PCB. 427 * 428 * The options given represent the choices made from the options 429 * returned from get_export_options. 430 * 431 * Call with options == NULL to start the primary GUI (create a 432 * main window, print, export, etc). 433 */ 434 435 void (*uninit) (HID *hid); 436 /*!< uninit a GUI hid. */ 437 438 void (*do_exit) (HID *hid); 439 /*!< uninit a GUI hid. */ 440 441 void (*parse_arguments) (int *argc_, char ***argv_); 442 /*!< Parse the command line. 443 * 444 * Call this early for whatever HID will be the primary HID, as it 445 * will set all the registered attributes. 446 * 447 * The HID should remove all arguments, leaving any possible file 448 * names behind. 449 */ 450 451 void (*invalidate_lr) (Coord left_, Coord right_, 452 Coord top_, Coord bottom_); 453 /*!< This may be called to ask the GUI to force a redraw of a 454 * given area. 455 */ 456 457 void (*invalidate_all) (void); 458 459 void (*notify_crosshair_change) (bool changes_complete); 460 461 void (*notify_mark_change) (bool changes_complete); 462 463 int (*set_layer) (const char *name_, int group_, int _empty); 464 /*!< During redraw or print/export cycles, this is called once per 465 * layer (or layer group, for copper layers). 466 * 467 * If it returns false (zero), the HID does not want that layer, 468 * and none of the drawing functions should be called. 469 * 470 * If it returns true (nonzero), the items in that layer [group] 471 * should be drawn using the various drawing functions. 472 * 473 * In addition to the MAX_GROUP copper layer groups, you may 474 * select layers indicated by the macros SL_* defined above, or 475 * any others with an index of -1. 476 * 477 * For copper layer groups, you may pass NULL for name to have a 478 * name fetched from the PCB struct. 479 * 480 * The EMPTY argument is a hint - if set, the layer is empty, if 481 * zero it may be non-empty. 482 */ 483 484 void (*end_layer) (void); 485 /*!< Tell the GUI the layer last selected has been finished with. */ 486 487 HID_DRAW *graphics; 488 489 void (*calibrate) (double xval_, double yval_); 490 /*!< This is for the printer. 491 * 492 * If you call this for the GUI, \c xval_ and \c yval_ are ignored, 493 * and a dialog pops up to lead you through the calibration 494 * procedure. 495 * 496 * For the printer, if \c xval_ and \c yval_ are zero, a 497 * calibration page is printed with instructions for calibrating 498 * your printer. 499 * 500 * After calibrating, nonzero \c xval_ and \c yval_ are passed 501 * according to the instructions. 502 * 503 * Metric is nonzero if the user prefers metric units, else inches 504 * are used. 505 */ 506 507 /* GUI layout functions. Not used or defined for print/export 508 HIDs. */ 509 510 /* Temporary */ 511 int (*shift_is_pressed) (void); 512 513 int (*control_is_pressed) (void); 514 int (*mod1_is_pressed) (void); 515 516 void (*get_coords) (const char *msg_, Coord *x_, Coord *y_); 517 518 void (*set_crosshair) (int x_, int y_, int cursor_action_); 519 /*!< Sets the crosshair, which may differ from the pointer 520 * depending on grid and pad snap. 521 * 522 * \note Note that the HID is responsible for hiding, showing, 523 * redrawing, etc. The core just tells it what coordinates it's 524 * actually using. 525 * 526 * \note Note that this routine may need to know what "pcb units" 527 * are so it can display them in mm or mils accordingly. 528 * 529 * If \c cursor_action_ is set, the cursor or screen may be 530 * adjusted so that the cursor and the crosshair are at the same 531 * point on the screen. 532 */ 533 #define HID_SC_DO_NOTHING 0 534 535 #define HID_SC_WARP_POINTER 1 536 537 #define HID_SC_PAN_VIEWPORT 2 538 539 #define HID_SC_CENTER_IN_VIEWPORT 3 540 541 #define HID_SC_CENTER_IN_VIEWPORT_AND_WARP_POINTER 4 542 543 hidval (*add_timer) (void (*func) (hidval user_data_), 544 unsigned long milliseconds_, hidval user_data_); 545 /*!< Causes func to be called at some point in the future. 546 * 547 * Timers are only good for *one* call; if you want it to 548 * repeat, add another timer during the callback for the first. 549 * 550 * \c user_data can be anything, it's just passed to func. 551 * 552 * \warning Times are not guaranteed to be accurate. 553 */ 554 555 void (*stop_timer) (hidval timer_); 556 /*!< Use this to stop a timer that hasn't triggered yet. */ 557 558 hidval (*watch_file) (int fd_, unsigned int condition_, void (*func_) (hidval watch_, int fd_, unsigned int condition_, hidval user_data_), 559 hidval user_data); 560 /*!< Causes \c func_ to be called when some condition occurs on 561 * the file descriptor passed. 562 * 563 * Conditions include data for reading, writing, hangup, and 564 * errors. 565 * 566 * \c user_data can be anything, it's just passed to \c func_. 567 */ 568 569 void (*unwatch_file) (hidval watch_); 570 /*!< Use this to stop a file watch. */ 571 572 hidval (*add_block_hook) (void (*func_) (hidval data_), hidval data_); 573 /*!< Causes \c func to be called in the main loop prior to 574 * blocking. 575 */ 576 577 void (*stop_block_hook) (hidval block_hook_); 578 /*!< Use this to stop a main loop block hook. */ 579 580 /* Various dialogs */ 581 582 void (*log) (const char *fmt_, ...); 583 /*!< Log a message to the log window. */ 584 585 void (*logv) (const char *fmt_, va_list args_); 586 /*!< Log a message to the log window. */ 587 588 int (*confirm_dialog) (char *msg_, ...); 589 /*!< A generic yes/no dialog. 590 * 591 * Returns zero if the cancel button is pressed, one for the ok 592 * button. 593 * 594 * If you specify alternate labels for ..., they are used instead 595 * of the default OK/Cancel ones, and the return value is the 596 * index of the label chosen. 597 * 598 * \warning You MUST pass NULL as the last parameter to this. 599 */ 600 601 int (*close_confirm_dialog) (); 602 /*!< A close confirmation dialog for unsaved pages, for example, 603 * with options "Close without saving", "Cancel" and "Save". 604 * 605 * Returns zero if the close is cancelled, or one if it should 606 * proceed. 607 * 608 * The HID is responsible for any "Save" action the user may wish 609 * before confirming the close. 610 */ 611 #define HID_CLOSE_CONFIRM_CANCEL 0 612 613 #define HID_CLOSE_CONFIRM_OK 1 614 615 void (*report_dialog) (char *title_, char *msg_); 616 /*!< Just prints text. */ 617 618 char *(*prompt_for) (const char *msg_, const char *default_string_); 619 /*!< Prompts the user to enter a string, returns the string. 620 * 621 * If \c default_string isn't NULL, the form is pre-filled with 622 * this value. 623 * 624 * "msg" is like "Enter value:". 625 */ 626 627 #define HID_FILESELECT_READ 0x01 628 /*!< Prompts the user for a filename or directory name. 629 * 630 * For GUI HID's this would mean a file select dialog box. 631 * 632 * The 'flags' argument is the bitwise OR of the following values. 633 */ 634 635 #define HID_FILESELECT_MAY_NOT_EXIST 0x02 636 /*!< The function calling hid->fileselect will deal with the case 637 * where the selected file already exists. 638 * 639 * If not given, then the gui will prompt with an "overwrite?" 640 * prompt. 641 * 642 * Only used when writing. 643 */ 644 645 #define HID_FILESELECT_IS_TEMPLATE 0x04 646 /*!< The call is supposed to return a file template (for gerber 647 * output for example) instead of an actual file. 648 * 649 * Only used when writing. 650 */ 651 652 char *(*fileselect) (const char *title_, const char *descr_, 653 char *default_file_, char *default_ext_, 654 const char *history_tag_, int flags_); 655 /*!< \c title_ may be used as a dialog box title. Ignored if NULL. 656 * 657 * \c descr_ is a longer help string. Ignored if NULL. 658 * 659 * \c default_file_ is the default file name. Ignored if NULL. 660 * 661 * \c default_ext_ is the default file extension, like ".pdf". 662 * Ignored if NULL. 663 * 664 * \c history_tag_ may be used by the GUI to keep track of file 665 * history. Examples would be "board", "vendor", "renumber", 666 * etc. If NULL, no specific history is kept. 667 * 668 * \c flags_ are the bitwise or of the HID_FILESELECT defines 669 * above. 670 */ 671 672 int (*attribute_dialog) (HID_Attribute * attrs_, 673 int n_attrs_, HID_Attr_Val * results_, 674 const char * title_, const char * descr_); 675 /*!< A generic dialog to ask for a set of attributes. 676 * 677 * If \c n_attrs_ is zero, \c attrs(.name) must be NULL terminated. 678 * 679 * Returns non-zero if an error occurred (usually, this means the 680 * user cancelled the dialog or something). 681 * 682 * \c title_ is the title of the dialog box. 683 * 684 * \c descr_ (if not NULL) can be a longer description of what the 685 * attributes are used for. 686 * 687 * The HID may choose to ignore it or it may use it for a tooltip 688 * or text in a dialog box, or a help string. 689 */ 690 691 void (*show_item) (void *item_); 692 /*!< This causes a second window to display, which only shows the 693 * selected item. 694 * 695 * The expose callback is called twice; once to size the extents 696 * of the item, and once to draw it. 697 * 698 * To pass magic values, pass the address of a variable created 699 * for this purpose. 700 */ 701 702 void (*beep) (void); 703 /*!< Something to alert the user. */ 704 705 int (*progress) (int so_far_, int total_, const char *message_); 706 /*!< Used by optimizers and autorouter to show progress to the 707 * user. 708 * 709 * Pass all zeros to flush display and remove any dialogs. 710 * 711 * Returns nonzero if the user wishes to cancel the operation. 712 */ 713 714 HID_DRC_GUI *drc_gui; 715 716 void (*edit_attributes) (char *owner, AttributeListType *attrlist_); 717 718 /* Debug drawing support. These APIs must be implemented (non NULL), 719 * but they do not have to be functional. request_debug_draw can 720 * return NULL to indicate debug drawing is not permitted. 721 * 722 * Debug drawing is not guaranteed to be re-entrant. 723 * The caller must not nest requests for debug drawing. 724 */ 725 726 HID_DRAW *(*request_debug_draw) (void); 727 /*!< Request permission for debug drawing. 728 * 729 * Returns a HID_DRAW pointer which should be used rather than the 730 * global gui->graphics-> for making drawing calls. 731 * 732 * If the return value is NULL, then permission has been denied, 733 * and the drawing must not continue. 734 * 735 * \warning Debug drawing is not guaranteed to be re-entrant. 736 * The caller must not nest requests for debug drawing. 737 */ 738 739 void (*flush_debug_draw) (void); 740 /*!< Flush pending drawing to the screen. 741 * 742 * May be implemented as a NOOP if the GUI has chosen to send the 743 * debug drawing directly to the screen. 744 */ 745 746 void (*finish_debug_draw) (void); 747 /*!< When finished, the user must inform the GUI to clean up 748 * resources. 749 * 750 * Any remaining rendering will be flushed to the screen. 751 */ 752 753 void (*notify_save_pcb) (const char *filename, bool done); 754 /*!< Notification to the GUI around saving the PCB file. 755 * 756 * Called with a false parameter before the save, called again 757 * with true after the save. 758 * 759 * Allows GUIs which watch for file-changes on disk to ignore 760 * our deliberate changes. 761 */ 762 763 void (*notify_filename_changed) (void); 764 /*!< Notification to the GUI that the PCB file has been renamed. */ 765 }; 766 767 /*! 768 * \brief Call this as soon as possible from main(). 769 * 770 * No other HID calls are valid until this is called. 771 */ 772 void hid_init (void); 773 774 /*! 775 * \brief Call this at exit. 776 */ 777 void hid_uninit (void); 778 779 /*! 780 * \brief When PCB runs in interactive mode, this is called to 781 * instantiate one GUI HID which happens to be the GUI. 782 * 783 * This HID is the one that interacts with the mouse and keyboard. 784 */ 785 HID *hid_find_gui (); 786 787 /*! 788 * \brief Finds the one printer HID and instantiates it. 789 */ 790 HID *hid_find_printer (void); 791 792 /*! 793 * \brief Finds the indicated exporter HID and instantiates it. 794 */ 795 HID *hid_find_exporter (const char *); 796 797 /*! 798 * \brief This returns a NULL-terminated array of available HIDs. 799 * 800 * The only real reason to use this is to locate all the export-style 801 * HIDs. 802 */ 803 HID **hid_enumerate (void); 804 805 /*! 806 * \brief This function (in the common code) will be called whenever 807 * the GUI needs to redraw the screen, print the board, or export a 808 * layer. 809 * 810 * If item is not NULL, only draw the given item. 811 * Item is only non-NULL if the HID was created via show_item. 812 * 813 * Each time func is called, it should do the following: 814 * 815 * allocate any colors needed, via get_color. 816 * 817 * cycle through the layers, calling set_layer for each layer to be 818 * drawn, and only drawing elements (all or specified) of desired 819 * layers. 820 * 821 * Do *not* assume that the hid that is passed is the GUI hid. 822 * 823 * This callback is also used for printing and exporting. 824 */ 825 void hid_expose_callback (HID * hid_, struct BoxType *region_, void *item_); 826 827 extern HID *gui; 828 /*!< This is initially set to a "no-gui" gui, and later reset by 829 * main. 830 * 831 * hid_expose_callback also temporarily set it for drawing. 832 */ 833 834 extern HID *exporter; 835 /*!< This is either NULL or points to the current HID that is being 836 * called to do the exporting. 837 * 838 * The gui HIDs set and unset this var. 839 */ 840 841 extern HID_Action *current_action; 842 /*!< This is either NULL or points to the current HID_Action that is 843 * being called. 844 * 845 * The action launcher sets and unsets this variable. 846 */ 847 848 extern int pixel_slop; 849 /*!< The GUI may set this to be approximately the PCB size of a 850 * pixel, to allow for near-misses in selection and changes in 851 * drawing items smaller than a screen pixel. 852 */ 853 854 #if defined(__cplusplus) && __cplusplus 855 } 856 #endif 857 858 #endif 859