6 /* Human Interface Device */
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.
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
23 The main structure is at the end of this file.
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.
31 #if defined(__cplusplus) && __cplusplus
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
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. */
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
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
;
62 #define HIDCONCAT(a,b) a##b
64 /* This is used to register the action callbacks (for menus and
65 whatnot). HID assumes the following actions are available for its
72 /* This is matched against action names in the GUI configuration */
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
82 int (*trigger_cb
) (int argc
, char **argv
, int x
, int y
);
83 /* Short description that sometimes accompanies the name. */
84 const char *description
;
85 /* Full allowed syntax; use \n to separate lines. */
89 /* This global variable is always set to the action context, before
90 an action callback is called. Action context can be specified
91 when registering an action with hid_register_action() Intended
92 for plugins with hub action callbacks. */
93 extern void *hid_action_context
;
95 /* Register a singe action associated with an action context. Makes
96 a copy of HID_Action. Intended for plugins to register actions
97 with a hub callback. */
98 extern void hid_register_action(const HID_Action
*, void *);
100 /* Deregister an action registered using hid_register_action().
101 Action context pointer is copied in the 2nd argument if it's not
102 NULL. Intended for plugins to deregister custom actions. */
103 extern void hid_deregister_action(const char *, void **);
105 /* Register a list of static actions without action context */
106 extern void hid_register_actions (HID_Action
*, int);
108 #define REGISTER_ACTIONS(a) HIDCONCAT(void register_,a) ()\
109 { hid_register_actions(a, sizeof(a)/sizeof(a[0])); }
111 /* Note that PCB expects the gui to provide the following actions:
121 extern const char pcbchanged_help
[];
122 extern const char pcbchanged_syntax
[];
123 extern const char routestyleschanged_help
[];
124 extern const char routestyleschanged_syntax
[];
125 extern const char netlistchanged_help
[];
126 extern const char netlistchanged_syntax
[];
127 extern const char layerschanged_help
[];
128 extern const char layerschanged_syntax
[];
129 extern const char librarychanged_help
[];
130 extern const char librarychanged_syntax
[];
132 int hid_action (const char *action_
);
133 int hid_actionl (const char *action_
, ...); /* NULL terminated */
134 int hid_actionv (const char *action_
, int argc_
, char **argv_
);
135 void hid_save_settings (int);
136 void hid_load_settings (void);
138 /* Parse the given string into action calls, and call `f' for each
139 action found. Returns nonzero if the action handler(s) return
140 nonzero. If f is NULL, hid_actionv is called. */
141 int hid_parse_actions (const char *str_
,
142 int (*_f
) (const char *, int, char **));
146 /* Name of the flag */
148 /* Function to call to get the value of the flag. */
149 int (*function
) (int);
150 /* Additional parameter to pass to that function. */
154 extern void hid_register_flags (HID_Flag
*, int);
155 #define REGISTER_FLAGS(a) HIDCONCAT(void register_,a) ()\
156 { hid_register_flags(a, sizeof(a)/sizeof(a[0])); }
158 /* Looks up one of the flags registered above. If the flag is
159 unknown, returns zero. */
160 int hid_get_flag (const char *name_
);
162 /* Used for HID attributes (exporting and printing, mostly).
163 HA_boolean uses int_value, HA_enum sets int_value to the index and
164 str_value to the enumeration string. HID_Label just shows the
165 default str_value. HID_Mixed is a real_value followed by an enum,
166 like 0.5in or 100mm. */
177 /* If the help_text is this, usage() won't show this option */
178 #define ATTR_UNDOCUMENTED ((char *)(1))
181 { HID_Label
, HID_Integer
, HID_Real
, HID_String
,
182 HID_Boolean
, HID_Enum
, HID_Mixed
, HID_Path
184 int min_val
, max_val
; /* for integer and real */
185 HID_Attr_Val default_val
; /* Also actual value for global attributes. */
186 const char **enumerations
;
187 /* If set, this is used for global attributes (i.e. those set
188 statically with REGISTER_ATTRIBUTES below) instead of changing
189 the default_val. Note that a HID_Mixed attribute must specify a
190 pointer to HID_Attr_Val here, and HID_Boolean assumes this is
191 "char *" so the value should be initialized to zero, and may be
192 set to non-zero (not always one). */
194 int hash
; /* for detecting changes. */
197 extern void hid_register_attributes (HID_Attribute
*, int);
198 #define REGISTER_ATTRIBUTES(a) HIDCONCAT(void register_,a) ()\
199 { hid_register_attributes(a, sizeof(a)/sizeof(a[0])); }
201 /* These three are set by hid_parse_command_line(). */
202 extern char *program_name
;
203 extern char *program_directory
;
204 extern char *program_basename
;
206 #define SL_0_SIDE 0x0000
207 #define SL_TOP_SIDE 0x0001
208 #define SL_BOTTOM_SIDE 0x0002
209 #define SL_SILK 0x0010
210 #define SL_MASK 0x0020
211 #define SL_PDRILL 0x0030
212 #define SL_UDRILL 0x0040
213 #define SL_PASTE 0x0050
214 #define SL_INVISIBLE 0x0060
215 #define SL_FAB 0x0070
216 #define SL_ASSY 0x0080
217 /* Callers should use this. */
218 #define SL(type,side) (~0xfff | SL_##type | SL_##side##_SIDE)
220 /* File Watch flags */
221 /* Based upon those in dbus/dbus-connection.h */
224 PCB_WATCH_READABLE
= 1 << 0, /**< As in POLLIN */
225 PCB_WATCH_WRITABLE
= 1 << 1, /**< As in POLLOUT */
226 PCB_WATCH_ERROR
= 1 << 2, /**< As in POLLERR */
227 PCB_WATCH_HANGUP
= 1 << 3 /**< As in POLLHUP */
233 int log_drc_overview
;
234 int log_drc_violations
;
235 void (*reset_drc_dialog_message
) (void);
236 void (*append_drc_violation
) (DrcViolationType
*violation
);
237 int (*throw_drc_dialog
) (void);
241 /* This is the main HID structure. */
244 /* The size of this structure. We use this as a compatibility
245 check; a HID built with a different hid.h than we're expecting
246 should have a different size here. */
249 /* The name of this HID. This should be suitable for
250 command line options, multi-selection menus, file names,
254 /* Likewise, but allowed to be longer and more descriptive. */
255 const char *description
;
257 /* If set, this is the GUI HID. Exactly one of these three flags
258 must be set; setting "gui" lets the expose callback optimize and
259 coordinate itself. */
262 /* If set, this is the printer-class HID. The common part of PCB
263 may use this to do command-line printing, without having
264 instantiated any GUI HIDs. Only one printer HID is normally
265 defined at a time. */
268 /* If set, this HID provides an export option, and should be used as
269 part of the File->Export menu option. Examples are PNG, Gerber,
270 and EPS exporters. */
273 /* If set, the redraw code will draw polygons before erasing the
277 /* If set, the redraw code will draw polygons after erasing the
278 clearances. Note that HIDs may set both of these, in which case
279 polygons will be drawn twice. */
282 /* If set, the redraw code will dice the polygons, so that there
283 are no clearances in any polygons. */
286 /* Returns a set of resources describing options the export or print
287 HID supports. In GUI mode, the print/export dialogs use this to
288 set up the selectable options. In command line mode, these are
289 used to interpret command line options. If n_ret is non-NULL,
290 the number of attributes is stored there. */
291 HID_Attribute
*(*get_export_options
) (int *n_ret_
);
293 /* Export (or print) the current PCB. The options given represent
294 the choices made from the options returned from
295 get_export_options. Call with options == NULL to start the
296 primary GUI (create a main window, print, export, etc) */
297 void (*do_export
) (HID_Attr_Val
* options_
);
299 /* Parse the command line. Call this early for whatever HID will be
300 the primary HID, as it will set all the registered attributes.
301 The HID should remove all arguments, leaving any possible file
303 void (*parse_arguments
) (int *argc_
, char ***argv_
);
305 /* This may be called outside of redraw to force a redraw. Pass
306 zero for "last" for all but the last call before control returns
307 to the user (pass nonzero the last time). If determining the
308 last call is difficult, call *_wh at the end with width and
310 void (*invalidate_wh
) (int x_
, int y_
, int width_
, int height_
, int last_
);
311 void (*invalidate_lr
) (int left_
, int right_
, int top_
, int bottom_
,
313 void (*invalidate_all
) (void);
315 /* During redraw or print/export cycles, this is called once per
316 layer (or layer group, for copper layers). If it returns false
317 (zero), the HID does not want that layer, and none of the drawing
318 functions should be called. If it returns true (nonzero), the
319 items in that layer [group] should be drawn using the various
320 drawing functions. In addition to the MAX_LAYERS copper layer
321 groups, you may select layers indicated by the macros SL_*
322 defined above, or any others with an index of -1. For copper
323 layer groups, you may pass NULL for name to have a name fetched
324 from the PCB struct. The EMPTY argument is a hint - if set, the
325 layer is empty, if zero it may be non-empty. */
326 int (*set_layer
) (const char *name_
, int group_
, int _empty
);
328 /* Drawing Functions. Coordinates and distances are ALWAYS in PCB's
329 default coordinates (1/100 mil at the time this comment was
330 written). Angles are always in degrees, with 0 being "right"
331 (positive X) and 90 being "up" (positive Y). */
333 /* Make an empty graphics context. */
334 hidGC (*make_gc
) (void);
335 void (*destroy_gc
) (hidGC gc_
);
337 /* Special note about the "erase" color: To use this color, you must
338 use this function to tell the HID when you're using it. At the
339 beginning of a layer redraw cycle (i.e. after set_layer), call
340 use_mask() to redirect output to a buffer. Draw to the buffer
341 (using regular HID calls) using regular and "erase" colors. Then
342 call use_mask(HID_MASK_OFF) to flush the buffer to the HID. If
343 you use the "erase" color when use_mask is disabled, it simply
344 draws in the background color. */
345 void (*use_mask
) (int use_it_
);
346 /* Flush the buffer and return to non-mask operation. */
347 #define HID_MASK_OFF 0
348 /* Polygons being drawn before clears. */
349 #define HID_MASK_BEFORE 1
350 /* Clearances being drawn. */
351 #define HID_MASK_CLEAR 2
352 /* Polygons being drawn after clears. */
353 #define HID_MASK_AFTER 3
354 /* Set to do live drawing on the screen */
355 #define HID_LIVE_DRAWING 4
356 /* stop live drawing on the screen */
357 #define HID_LIVE_DRAWING_OFF 5
358 /* flush any queued drawing */
359 #define HID_FLUSH_DRAW_Q 6
361 /* Set a color. Names can be like "red" or "#rrggbb" or special
362 names like "erase". *Always* use the "erase" color for removing
363 ink (like polygon reliefs or thermals), as you cannot rely on
364 knowing the background color or special needs of the HID. Always
365 use the "drill" color to draw holes. You may assume this is
366 cheap enough to call inside the redraw callback, but not cheap
367 enough to call for each item drawn. */
368 void (*set_color
) (hidGC gc_
, const char *name_
);
370 /* Set the line style. While calling this is cheap, calling it with
371 different values each time may be expensive, so grouping items by
372 line style is helpful. */
373 void (*set_line_cap
) (hidGC gc_
, EndCapStyle style_
);
374 void (*set_line_width
) (hidGC gc_
, int width_
);
375 void (*set_draw_xor
) (hidGC gc_
, int xor_
);
376 /* Blends 20% or so color with 80% background. Only used for
377 assembly drawings so far. */
378 void (*set_draw_faded
) (hidGC gc_
, int faded_
);
380 /* When you pass the same x,y twice to draw_line, the end caps are
381 drawn as if the "line" were parallel to the line defined by these
382 coordinates. Use this for rotating non-round pads. */
383 void (*set_line_cap_angle
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
385 /* The usual drawing functions. "draw" means to use segments of the
386 given width, whereas "fill" means to fill to a zero-width
388 void (*draw_line
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
389 void (*draw_arc
) (hidGC gc_
, int cx_
, int cy_
, int xradius_
, int yradius_
,
390 int start_angle_
, int delta_angle_
);
391 void (*draw_rect
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
392 void (*fill_circle
) (hidGC gc_
, int cx_
, int cy_
, int radius_
);
393 void (*fill_polygon
) (hidGC gc_
, int n_coords_
, int *x_
, int *y_
);
394 void (*fill_pcb_polygon
) (hidGC gc_
, PolygonType
*poly
,
395 const BoxType
*clip_box
);
396 void (*thindraw_pcb_polygon
) (hidGC gc_
, PolygonType
*poly
,
397 const BoxType
*clip_box
);
398 void (*fill_rect
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
401 /* This is for the printer. If you call this for the GUI, xval and
402 yval are ignored, and a dialog pops up to lead you through the
403 calibration procedure. For the printer, if xval and yval are
404 zero, a calibration page is printed with instructions for
405 calibrating your printer. After calibrating, nonzero xval and
406 yval are passed according to the instructions. Metric is nonzero
407 if the user prefers metric units, else inches are used. */
408 void (*calibrate
) (double xval_
, double yval_
);
411 /* GUI layout functions. Not used or defined for print/export
415 int (*shift_is_pressed
) (void);
416 int (*control_is_pressed
) (void);
417 int (*mod1_is_pressed
) (void);
418 void (*get_coords
) (const char *msg_
, int *x_
, int *y_
);
420 /* Sets the crosshair, which may differ from the pointer depending
421 on grid and pad snap. Note that the HID is responsible for
422 hiding, showing, redrawing, etc. The core just tells it what
423 coordinates it's actually using. Note that this routine may
424 need to know what "pcb units" are so it can display them in mm
425 or mils accordingly. If cursor_action is set, the cursor or
426 screen may be adjusted so that the cursor and the crosshair are
427 at the same point on the screen. */
428 void (*set_crosshair
) (int x_
, int y_
, int cursor_action_
);
429 #define HID_SC_DO_NOTHING 0
430 #define HID_SC_WARP_POINTER 1
431 #define HID_SC_PAN_VIEWPORT 2
433 /* Causes func to be called at some point in the future. Timers are
434 only good for *one* call; if you want it to repeat, add another
435 timer during the callback for the first. user_data can be
436 anything, it's just passed to func. Times are not guaranteed to
438 hidval (*add_timer
) (void (*func
) (hidval user_data_
),
439 unsigned long milliseconds_
, hidval user_data_
);
440 /* Use this to stop a timer that hasn't triggered yet. */
441 void (*stop_timer
) (hidval timer_
);
443 /* Causes func to be called when some condition occurs on the file
444 descriptor passed. Conditions include data for reading, writing,
445 hangup, and errors. user_data can be anything, it's just passed
447 hidval (*watch_file
) (int fd_
, unsigned int condition_
, void (*func_
) (hidval watch_
, int fd_
, unsigned int condition_
, hidval user_data_
),
449 /* Use this to stop a file watch. */
450 void (*unwatch_file
) (hidval watch_
);
452 /* Causes func to be called in the mainloop prior to blocking */
453 hidval (*add_block_hook
) (void (*func_
) (hidval data_
), hidval data_
);
454 /* Use this to stop a mainloop block hook. */
455 void (*stop_block_hook
) (hidval block_hook_
);
457 /* Various dialogs */
459 /* Log a message to the log window. */
460 void (*log
) (const char *fmt_
, ...);
461 void (*logv
) (const char *fmt_
, va_list args_
);
463 /* A generic yes/no dialog. Returns zero if the cancel button is
464 pressed, one for the ok button. If you specify alternate labels
465 for ..., they are used instead of the default OK/Cancel ones, and
466 the return value is the index of the label chosen. You MUST pass
467 NULL as the last parameter to this. */
468 int (*confirm_dialog
) (char *msg_
, ...);
470 /* A close confirmation dialog for unsaved pages, for example, with
471 options "Close without saving", "Cancel" and "Save". Returns zero
472 if the close is cancelled, or one if it should proceed. The HID
473 is responsible for any "Save" action the user may wish before
474 confirming the close.
476 int (*close_confirm_dialog
) ();
477 #define HID_CLOSE_CONFIRM_CANCEL 0
478 #define HID_CLOSE_CONFIRM_OK 1
480 /* Just prints text. */
481 void (*report_dialog
) (char *title_
, char *msg_
);
483 /* Prompts the user to enter a string, returns the string. If
484 default_string isn't NULL, the form is pre-filled with this
485 value. "msg" is like "Enter value:". */
486 char *(*prompt_for
) (char *msg_
, char *default_string_
);
488 /* Prompts the user for a filename or directory name. For GUI
489 HID's this would mean a file select dialog box. The 'flags'
490 argument is the bitwise OR of the following values. */
491 #define HID_FILESELECT_READ 0x01
493 /* The function calling hid->fileselect will deal with the case
494 where the selected file already exists. If not given, then the
495 gui will prompt with an "overwrite?" prompt. Only used when
498 #define HID_FILESELECT_MAY_NOT_EXIST 0x02
500 /* The call is supposed to return a file template (for gerber
501 output for example) instead of an actual file. Only used when
504 #define HID_FILESELECT_IS_TEMPLATE 0x04
506 /* title may be used as a dialog box title. Ignored if NULL.
508 * descr is a longer help string. Ignored if NULL.
510 * default_file is the default file name. Ignored if NULL.
512 * default_ext is the default file extension, like ".pdf".
515 * history_tag may be used by the GUI to keep track of file
516 * history. Examples would be "board", "vendor", "renumber",
517 * etc. If NULL, no specific history is kept.
519 * flags are the bitwise or of the HID_FILESELECT defines above
522 char *(*fileselect
) (const char *title_
, const char *descr_
,
523 char *default_file_
, char *default_ext_
,
524 const char *history_tag_
, int flags_
);
526 /* A generic dialog to ask for a set of attributes. If n_attrs is
527 zero, attrs(.name) must be NULL terminated. Returns non-zero if
528 an error occurred (usually, this means the user cancelled the
529 dialog or something). title is the title of the dialog box
530 descr (if not NULL) can be a longer description of what the
531 attributes are used for. The HID may choose to ignore it or it
532 may use it for a tooltip or text in a dialog box, or a help
535 int (*attribute_dialog
) (HID_Attribute
* attrs_
,
536 int n_attrs_
, HID_Attr_Val
* results_
,
537 const char * title_
, const char * descr_
);
539 /* This causes a second window to display, which only shows the
540 selected item. The expose callback is called twice; once to size
541 the extents of the item, and once to draw it. To pass magic
542 values, pass the address of a variable created for this
544 void (*show_item
) (void *item_
);
546 /* Something to alert the user. */
549 /* Used by optimizers and autorouter to show progress to the user.
550 Pass all zeros to flush display and remove any dialogs.
551 Returns nonzero if the user wishes to cancel the operation. */
552 int (*progress
) (int so_far_
, int total_
, const char *message_
);
554 HID_DRC_GUI
*drc_gui
;
558 /* Call this as soon as possible from main(). No other HID calls are
559 valid until this is called. */
560 void hid_init (void);
562 /* When PCB runs in interactive mode, this is called to instantiate
563 one GUI HID which happens to be the GUI. This HID is the one that
564 interacts with the mouse and keyboard. */
565 HID
*hid_find_gui ();
567 /* Finds the one printer HID and instantiates it. */
568 HID
*hid_find_printer (void);
570 /* Finds the indicated exporter HID and instantiates it. */
571 HID
*hid_find_exporter (const char *);
573 /* This returns a NULL-terminated array of available HIDs. The only
574 real reason to use this is to locate all the export-style HIDs. */
575 HID
**hid_enumerate (void);
577 /* This function (in the common code) will be called whenever the GUI
578 needs to redraw the screen, print the board, or export a layer. If
579 item is not NULL, only draw the given item. Item is only non-NULL
580 if the HID was created via show_item.
582 Each time func is called, it should do the following:
584 * allocate any colors needed, via get_color.
586 * cycle through the layers, calling set_layer for each layer to be
587 drawn, and only drawing elements (all or specified) of desired
590 Do *not* assume that the hid that is passed is the GUI hid. This
591 callback is also used for printing and exporting. */
593 void hid_expose_callback (HID
* hid_
, struct BoxType
*region_
, void *item_
);
595 /* This is initially set to a "no-gui" gui, and later reset by
599 /* This is either NULL or points to the current HID that is being called to
600 do the exporting. The gui HIDs set and unset this var.*/
601 extern HID
*exporter
;
603 /* The GUI may set this to be approximately the PCB size of a pixel,
604 to allow for near-misses in selection and changes in drawing items
605 smaller than a screen pixel. */
606 extern int pixel_slop
;
608 #if defined(__cplusplus) && __cplusplus