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:
115 NetlistChanged() (but core should call "void NetlistChanged(int);" in netlist.c)
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 #define SL_RATS 0x0090
218 /* Callers should use this. */
219 #define SL(type,side) (~0xfff | SL_##type | SL_##side##_SIDE)
221 /* File Watch flags */
222 /* Based upon those in dbus/dbus-connection.h */
225 PCB_WATCH_READABLE
= 1 << 0, /**< As in POLLIN */
226 PCB_WATCH_WRITABLE
= 1 << 1, /**< As in POLLOUT */
227 PCB_WATCH_ERROR
= 1 << 2, /**< As in POLLERR */
228 PCB_WATCH_HANGUP
= 1 << 3 /**< As in POLLHUP */
234 int log_drc_overview
;
235 int log_drc_violations
;
236 void (*reset_drc_dialog_message
) (void);
237 void (*append_drc_violation
) (DrcViolationType
*violation
);
238 int (*throw_drc_dialog
) (void);
242 /* This is the main HID structure. */
245 /* The size of this structure. We use this as a compatibility
246 check; a HID built with a different hid.h than we're expecting
247 should have a different size here. */
250 /* The name of this HID. This should be suitable for
251 command line options, multi-selection menus, file names,
255 /* Likewise, but allowed to be longer and more descriptive. */
256 const char *description
;
258 /* If set, this is the GUI HID. Exactly one of these three flags
259 must be set; setting "gui" lets the expose callback optimize and
260 coordinate itself. */
263 /* If set, this is the printer-class HID. The common part of PCB
264 may use this to do command-line printing, without having
265 instantiated any GUI HIDs. Only one printer HID is normally
266 defined at a time. */
269 /* If set, this HID provides an export option, and should be used as
270 part of the File->Export menu option. Examples are PNG, Gerber,
271 and EPS exporters. */
274 /* If set, the redraw code will draw polygons before erasing the
278 /* If set, the redraw code will draw polygons after erasing the
279 clearances. Note that HIDs may set both of these, in which case
280 polygons will be drawn twice. */
283 /* If set, the redraw code will dice the polygons, so that there
284 are no clearances in any polygons. */
287 /* Returns a set of resources describing options the export or print
288 HID supports. In GUI mode, the print/export dialogs use this to
289 set up the selectable options. In command line mode, these are
290 used to interpret command line options. If n_ret is non-NULL,
291 the number of attributes is stored there. */
292 HID_Attribute
*(*get_export_options
) (int *n_ret_
);
294 /* Export (or print) the current PCB. The options given represent
295 the choices made from the options returned from
296 get_export_options. Call with options == NULL to start the
297 primary GUI (create a main window, print, export, etc) */
298 void (*do_export
) (HID_Attr_Val
* options_
);
300 /* Parse the command line. Call this early for whatever HID will be
301 the primary HID, as it will set all the registered attributes.
302 The HID should remove all arguments, leaving any possible file
304 void (*parse_arguments
) (int *argc_
, char ***argv_
);
306 /* This may be called to ask the GUI to force a redraw of a given area */
307 void (*invalidate_lr
) (int left_
, int right_
, int top_
, int bottom_
);
308 void (*invalidate_all
) (void);
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
);
323 /* Drawing Functions. Coordinates and distances are ALWAYS in PCB's
324 default coordinates (1/100 mil at the time this comment was
325 written). Angles are always in degrees, with 0 being "right"
326 (positive X) and 90 being "up" (positive Y). */
328 /* Make an empty graphics context. */
329 hidGC (*make_gc
) (void);
330 void (*destroy_gc
) (hidGC gc_
);
332 /* Special note about the "erase" color: To use this color, you must
333 use this function to tell the HID when you're using it. At the
334 beginning of a layer redraw cycle (i.e. after set_layer), call
335 use_mask() to redirect output to a buffer. Draw to the buffer
336 (using regular HID calls) using regular and "erase" colors. Then
337 call use_mask(HID_MASK_OFF) to flush the buffer to the HID. If
338 you use the "erase" color when use_mask is disabled, it simply
339 draws in the background color. */
340 void (*use_mask
) (int use_it_
);
341 /* Flush the buffer and return to non-mask operation. */
342 #define HID_MASK_OFF 0
343 /* Polygons being drawn before clears. */
344 #define HID_MASK_BEFORE 1
345 /* Clearances being drawn. */
346 #define HID_MASK_CLEAR 2
347 /* Polygons being drawn after clears. */
348 #define HID_MASK_AFTER 3
349 /* Set to do live drawing on the screen */
350 #define HID_LIVE_DRAWING 4
351 /* stop live drawing on the screen */
352 #define HID_LIVE_DRAWING_OFF 5
353 /* flush any queued drawing */
354 #define HID_FLUSH_DRAW_Q 6
356 /* Set a color. Names can be like "red" or "#rrggbb" or special
357 names like "erase". *Always* use the "erase" color for removing
358 ink (like polygon reliefs or thermals), as you cannot rely on
359 knowing the background color or special needs of the HID. Always
360 use the "drill" color to draw holes. You may assume this is
361 cheap enough to call inside the redraw callback, but not cheap
362 enough to call for each item drawn. */
363 void (*set_color
) (hidGC gc_
, const char *name_
);
365 /* Set the line style. While calling this is cheap, calling it with
366 different values each time may be expensive, so grouping items by
367 line style is helpful. */
368 void (*set_line_cap
) (hidGC gc_
, EndCapStyle style_
);
369 void (*set_line_width
) (hidGC gc_
, int width_
);
370 void (*set_draw_xor
) (hidGC gc_
, int xor_
);
371 /* Blends 20% or so color with 80% background. Only used for
372 assembly drawings so far. */
373 void (*set_draw_faded
) (hidGC gc_
, int faded_
);
375 /* When you pass the same x,y twice to draw_line, the end caps are
376 drawn as if the "line" were parallel to the line defined by these
377 coordinates. Use this for rotating non-round pads. */
378 void (*set_line_cap_angle
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
380 /* The usual drawing functions. "draw" means to use segments of the
381 given width, whereas "fill" means to fill to a zero-width
383 void (*draw_line
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
384 void (*draw_arc
) (hidGC gc_
, int cx_
, int cy_
, int xradius_
, int yradius_
,
385 int start_angle_
, int delta_angle_
);
386 void (*draw_rect
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
387 void (*fill_circle
) (hidGC gc_
, int cx_
, int cy_
, int radius_
);
388 void (*fill_polygon
) (hidGC gc_
, int n_coords_
, int *x_
, int *y_
);
389 void (*fill_pcb_polygon
) (hidGC gc_
, PolygonType
*poly
,
390 const BoxType
*clip_box
);
391 void (*thindraw_pcb_polygon
) (hidGC gc_
, PolygonType
*poly
,
392 const BoxType
*clip_box
);
393 void (*fill_rect
) (hidGC gc_
, int x1_
, int y1_
, int x2_
, int y2_
);
396 /* This is for the printer. If you call this for the GUI, xval and
397 yval are ignored, and a dialog pops up to lead you through the
398 calibration procedure. For the printer, if xval and yval are
399 zero, a calibration page is printed with instructions for
400 calibrating your printer. After calibrating, nonzero xval and
401 yval are passed according to the instructions. Metric is nonzero
402 if the user prefers metric units, else inches are used. */
403 void (*calibrate
) (double xval_
, double yval_
);
406 /* GUI layout functions. Not used or defined for print/export
410 int (*shift_is_pressed
) (void);
411 int (*control_is_pressed
) (void);
412 int (*mod1_is_pressed
) (void);
413 void (*get_coords
) (const char *msg_
, int *x_
, int *y_
);
415 /* Sets the crosshair, which may differ from the pointer depending
416 on grid and pad snap. Note that the HID is responsible for
417 hiding, showing, redrawing, etc. The core just tells it what
418 coordinates it's actually using. Note that this routine may
419 need to know what "pcb units" are so it can display them in mm
420 or mils accordingly. If cursor_action is set, the cursor or
421 screen may be adjusted so that the cursor and the crosshair are
422 at the same point on the screen. */
423 void (*set_crosshair
) (int x_
, int y_
, int cursor_action_
);
424 #define HID_SC_DO_NOTHING 0
425 #define HID_SC_WARP_POINTER 1
426 #define HID_SC_PAN_VIEWPORT 2
428 /* Causes func to be called at some point in the future. Timers are
429 only good for *one* call; if you want it to repeat, add another
430 timer during the callback for the first. user_data can be
431 anything, it's just passed to func. Times are not guaranteed to
433 hidval (*add_timer
) (void (*func
) (hidval user_data_
),
434 unsigned long milliseconds_
, hidval user_data_
);
435 /* Use this to stop a timer that hasn't triggered yet. */
436 void (*stop_timer
) (hidval timer_
);
438 /* Causes func to be called when some condition occurs on the file
439 descriptor passed. Conditions include data for reading, writing,
440 hangup, and errors. user_data can be anything, it's just passed
442 hidval (*watch_file
) (int fd_
, unsigned int condition_
, void (*func_
) (hidval watch_
, int fd_
, unsigned int condition_
, hidval user_data_
),
444 /* Use this to stop a file watch. */
445 void (*unwatch_file
) (hidval watch_
);
447 /* Causes func to be called in the mainloop prior to blocking */
448 hidval (*add_block_hook
) (void (*func_
) (hidval data_
), hidval data_
);
449 /* Use this to stop a mainloop block hook. */
450 void (*stop_block_hook
) (hidval block_hook_
);
452 /* Various dialogs */
454 /* Log a message to the log window. */
455 void (*log
) (const char *fmt_
, ...);
456 void (*logv
) (const char *fmt_
, va_list args_
);
458 /* A generic yes/no dialog. Returns zero if the cancel button is
459 pressed, one for the ok button. If you specify alternate labels
460 for ..., they are used instead of the default OK/Cancel ones, and
461 the return value is the index of the label chosen. You MUST pass
462 NULL as the last parameter to this. */
463 int (*confirm_dialog
) (char *msg_
, ...);
465 /* A close confirmation dialog for unsaved pages, for example, with
466 options "Close without saving", "Cancel" and "Save". Returns zero
467 if the close is cancelled, or one if it should proceed. The HID
468 is responsible for any "Save" action the user may wish before
469 confirming the close.
471 int (*close_confirm_dialog
) ();
472 #define HID_CLOSE_CONFIRM_CANCEL 0
473 #define HID_CLOSE_CONFIRM_OK 1
475 /* Just prints text. */
476 void (*report_dialog
) (char *title_
, char *msg_
);
478 /* Prompts the user to enter a string, returns the string. If
479 default_string isn't NULL, the form is pre-filled with this
480 value. "msg" is like "Enter value:". */
481 char *(*prompt_for
) (char *msg_
, char *default_string_
);
483 /* Prompts the user for a filename or directory name. For GUI
484 HID's this would mean a file select dialog box. The 'flags'
485 argument is the bitwise OR of the following values. */
486 #define HID_FILESELECT_READ 0x01
488 /* The function calling hid->fileselect will deal with the case
489 where the selected file already exists. If not given, then the
490 gui will prompt with an "overwrite?" prompt. Only used when
493 #define HID_FILESELECT_MAY_NOT_EXIST 0x02
495 /* The call is supposed to return a file template (for gerber
496 output for example) instead of an actual file. Only used when
499 #define HID_FILESELECT_IS_TEMPLATE 0x04
501 /* title may be used as a dialog box title. Ignored if NULL.
503 * descr is a longer help string. Ignored if NULL.
505 * default_file is the default file name. Ignored if NULL.
507 * default_ext is the default file extension, like ".pdf".
510 * history_tag may be used by the GUI to keep track of file
511 * history. Examples would be "board", "vendor", "renumber",
512 * etc. If NULL, no specific history is kept.
514 * flags are the bitwise or of the HID_FILESELECT defines above
517 char *(*fileselect
) (const char *title_
, const char *descr_
,
518 char *default_file_
, char *default_ext_
,
519 const char *history_tag_
, int flags_
);
521 /* A generic dialog to ask for a set of attributes. If n_attrs is
522 zero, attrs(.name) must be NULL terminated. Returns non-zero if
523 an error occurred (usually, this means the user cancelled the
524 dialog or something). title is the title of the dialog box
525 descr (if not NULL) can be a longer description of what the
526 attributes are used for. The HID may choose to ignore it or it
527 may use it for a tooltip or text in a dialog box, or a help
530 int (*attribute_dialog
) (HID_Attribute
* attrs_
,
531 int n_attrs_
, HID_Attr_Val
* results_
,
532 const char * title_
, const char * descr_
);
534 /* This causes a second window to display, which only shows the
535 selected item. The expose callback is called twice; once to size
536 the extents of the item, and once to draw it. To pass magic
537 values, pass the address of a variable created for this
539 void (*show_item
) (void *item_
);
541 /* Something to alert the user. */
544 /* Used by optimizers and autorouter to show progress to the user.
545 Pass all zeros to flush display and remove any dialogs.
546 Returns nonzero if the user wishes to cancel the operation. */
547 int (*progress
) (int so_far_
, int total_
, const char *message_
);
549 HID_DRC_GUI
*drc_gui
;
551 void (*edit_attributes
) (char *owner
, AttributeListType
*attrlist_
);
555 /* Call this as soon as possible from main(). No other HID calls are
556 valid until this is called. */
557 void hid_init (void);
559 /* When PCB runs in interactive mode, this is called to instantiate
560 one GUI HID which happens to be the GUI. This HID is the one that
561 interacts with the mouse and keyboard. */
562 HID
*hid_find_gui ();
564 /* Finds the one printer HID and instantiates it. */
565 HID
*hid_find_printer (void);
567 /* Finds the indicated exporter HID and instantiates it. */
568 HID
*hid_find_exporter (const char *);
570 /* This returns a NULL-terminated array of available HIDs. The only
571 real reason to use this is to locate all the export-style HIDs. */
572 HID
**hid_enumerate (void);
574 /* This function (in the common code) will be called whenever the GUI
575 needs to redraw the screen, print the board, or export a layer. If
576 item is not NULL, only draw the given item. Item is only non-NULL
577 if the HID was created via show_item.
579 Each time func is called, it should do the following:
581 * allocate any colors needed, via get_color.
583 * cycle through the layers, calling set_layer for each layer to be
584 drawn, and only drawing elements (all or specified) of desired
587 Do *not* assume that the hid that is passed is the GUI hid. This
588 callback is also used for printing and exporting. */
590 void hid_expose_callback (HID
* hid_
, struct BoxType
*region_
, void *item_
);
592 /* This is initially set to a "no-gui" gui, and later reset by
596 /* This is either NULL or points to the current HID that is being called to
597 do the exporting. The gui HIDs set and unset this var.*/
598 extern HID
*exporter
;
600 /* The GUI may set this to be approximately the PCB size of a pixel,
601 to allow for near-misses in selection and changes in drawing items
602 smaller than a screen pixel. */
603 extern int pixel_slop
;
605 #if defined(__cplusplus) && __cplusplus