File: pl_editor.adoc

package info (click to toggle)
kicad 5.0.2+dfsg1-1~bpo9+1
  • links: PTS, VCS
  • area: main
  • in suites: stretch-backports
  • size: 234,600 kB
  • sloc: cpp: 505,330; ansic: 57,038; python: 4,886; sh: 879; awk: 294; makefile: 253; xml: 103; perl: 5
file content (714 lines) | stat: -rw-r--r-- 18,285 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
:author: The KiCad Team
:doctype: article
:revdate: @REVDATE@
:toc:
:ascii-ids:

= Pl_Editor

_Reference manual_

[[copyright]]
*Copyright*

This document is Copyright (C) 2015 by it's contributors as listed below.
You may distribute it and/or modify it under the terms of either the GNU
General Public License (http://www.gnu.org/licenses/gpl.html),
version 3 or later, or the Creative Commons Attribution License
(http://creativecommons.org/licenses/by/3.0/),
version 3.0 or later.

[[contributors]]
*Contributors*

Jean-Pierre Charras.

[[feedback]]
*Feedback*

Please direct any bug reports, suggestions or new versions to here:

- About KiCad document: https://github.com/KiCad/kicad-doc/issues

- About KiCad software: https://bugs.launchpad.net/kicad

- About KiCad software i18n: https://github.com/KiCad/kicad-i18n/issues

[[publication_date_and_software_version]]
*Publication date and software version*

may 23, 2015.

//Since docbook "article" is more compact, I have to separate this page
<<<<<

[[introduction-to-pl_editor]]
== Introduction to *Pl_Editor*

Pl_Editor is a page layout editor tool to create custom title blocks,
and frame references.

The title block, associated to frame references, and other graphic items
(logos) is called here a page layout.

Basic page layout items are:

* *Lines*

* *Rectangles*

* *Texts* (with format symbols, that will be replaced by the actual text,
  like the date, page number...) in Eeschema or Pcbnew.

* *Poly-polygons* (mainly to place logos and special graphic shapes)

* *Bitmaps*.

WARNING: Bitmaps can be plotted only by few plotters (PDF and
PS only) Therefore, for other plotters, only a bounding box will be
plotted.

* Items can be repeated, and texts and poly_polygons can be rotated.

[[pl_editor-files]]
== Pl_Editor files

[[input-file-and-default-title-block]]
=== Input file and default title block

Pl_Editor reads or writes page layout description files *.kicad_wks
(KiCad worksheet).

An internal default page layout description to display the default KiCad
title block is used until a file is read.

[[output-file]]
=== Output file

The current page layout description can be written in a **.kicad_wks*
file, using the S-expression format, which is widely used in KiCad.

This file can be used to show the custom page layout in Eeschema and/or
Pcbnew.

<<<<<

[[theory-of-operations]]
== Theory of operations

[[basic-page-layout-items-properties]]
=== Basic page layout items properties:

Basic page layout items are:

* *Lines*

* *Rectangles*

* *Texts* (with format symbols, with will be replaced by the actual
  text, like the date, page number...) in Eeschema or Pcbnew.

* *Poly-polygons* (mainly to place logos and special graphic shapes).
  These poly polygons are created by **Bitmap2component**, and cannot be
  built inside pl_editor, because it is not possible to create such shapes
  by hand.

* *Bitmaps* to place logos.

WARNING: Bitmaps can be plotted only by few plotters: PDF and PS only.

Therefore:

* *Texts, poly-polygons* and *bitmaps* are defined by a position, and
  can be rotated.

* *Lines* (in fact segments) and *rectangles* are defined by two points:
  a start point and a end point. They cannot be rotated (this is useless
  for segments).

These basic items can be repeated.

Texts which are repeated accept also an increment value for labels (has
meaning only if the text is one letter or one digit).

[[coordinates-definition]]
=== Coordinates definition

Each position, start point and end point of items is always relative to
a page corner.

**This feature ensure you can define a page layout which is not
dependent on the paper size**.

[[reference-corners-and-coordinates]]
=== Reference corners and coordinates:

image:images/en/page_property_1.png[]

* When the page size is changed, the position of the item, relative to
  its reference corner does not change.

* Usually, title blocks are attached to the right bottom corner, and
  therefore this corner is the default corner, when creating an item.

For rectangles and segments, which have two defined points, each point
has its reference corner.

<<<<<

[[rotation]]
=== Rotation

Items which have a position defined by just one point (texts and
poly-polygons) can be rotated:

Normal: Rotation = 0

image::images/en/text_noriented.png[scaledwidth="50%"]

Rotated: Rotation = 20 and 10 degrees.

image::images/en/text_rotated.png[scaledwidth="50%"]

<<<<<

[[repeat-option]]
=== Repeat option

Items can be repeated:

This is useful to create grid and grid labels.

image::images/en/page_property_2.png[scaledwidth="95%"]]

<<<<<

[[texts-and-formats]]
== Texts and formats

[[format-symbols]]
=== Format symbols:

Texts can be simple strings or can include format symbols.

Format symbols are replaced by the actual values in Eeschema or Pcbnew.

They are like format symbols in printf function.

A format symbol is *%* followed by 1 letter.

The *%C* format has one digit (comment identifier).

Formats symbols are:

*%% = replaced by %*

*%K = KiCad version*

*%Z = paper format name (A4, USLetter ...)*

*%Y = company name*

*%D = date*

*%R = revision*

*%S = sheet number*

*%N = number of sheets*

*%Cx = comment (x = 0 to 9 to identify the comment)*

*%F = filename*

*%P = sheet path (sheet full name, for Eeschema)*

*%T = title*

Example:

"Size: %Z" displays "Size: A4" or "Size: USLetter"

<<<<<

User display mode: image:images/icons/pagelayout_normal_view_mode.png[] activated.
Title block displayed like in Eeschema and Pcbnew

image::images/en/show_fields_data.png[scaledwidth="70%"]

"Native" display mode: image:images/icons/pagelayout_special_view_mode.png[] activated.
The native texts entered in Pl_Editor, with their format symbols.

image::images/en/show_fields_codes.png[scaledwidth="70%"]

<<<<<

[[multi-line-texts]]
=== Multi-line texts:

Texts can be multi-line.

There are 2 ways to insert a new line in texts:

1.  Insert the "\n" 2 chars sequence (mainly in Page setup dialog in
    KiCad).

2.  Insert a new line in Pl_Editor Design window.

Here is an example:

Setup

image::images/en/options_multi_line.png[scaledwidth="50%"]

Output

image::images/en/multi_line.png[scaledwidth="65%"]

<<<<<

[[multi-line-texts-in-page-setup-dialog]]
=== Multi-line texts in Page Setup dialog:

In the page setup dialog, text controls do not accept a multi-line text.

The *"\n"* 2 chars sequence should be inserted to force a new line inside a
text.

Here is a two lines text, in _comment 2_ field:

image:images/en/insert_newline_code.png[]

Here is the actual text:

image:images/en/multi_line_2.png[]

However, if you really want the *"\n"* inside the text, enter *"\\n"*.

image:images/en/insert_slashnewline_code.png[]

And the displayed text:

image:images/en/multi_line_3.png[]

<<<<<

[[constraints]]
== Constraints

[[page-1-constraint]]
=== Page 1 constraint

When using Eeschema, the full schematic often uses more than one page.

Usually page layout items are displayed on all pages.

But if a user want some items to be displayed only on page 1, or not on
page 1, the "page 1 option" this is possible by setting this option:

image:images/en/display_options.png[]

Page 1 option:

* None: no constraint.

* Page 1 only: the items is visible only on page 1.

* Not on page 1: the items is visible on all pages but the page 1.

<<<<<

[[text-full-size-constraint]]
=== Text full size constraint

image:images/en/constraint_options.png[]

Only for texts, one can set 2 parameters :

* the max size X

* the max size Y

which define a bounding box.

When these parameters are not 0, when displaying the text, the actual
text height and the actual text width are dynamically modified if the
full text size is bigger than the max size X and/or the max size Y, to
fit the full text size with this bounding box.

When the actual full text size is smaller than the max size X and/or the
max size Y, the text height and/or the text width is not modified.

The text with no bounding box. Max size X = 0,0 Max size Y = 0,0

image:images/en/constraints_none.png[]

The *same* text with constraint. Max size X = 40,0 Max size Y = 0,0

image:images/en/constraints_defined.png[]

<<<<<

A multi line text, constrained:

Setup

image:images/en/constraint_options.png[]

Output

image:images/en/block_constraints.png[]

<<<<<

[[invoking-pl_editor]]
== Invoking Pl_Editor

Pl_Editor is typically invoked from a command line, or from the KiCad
manager.

From a command line, the syntax is pl_editor <*.kicad_wks file to open>.

[[pl_editor-commands]]
== Pl_Editor Commands

[[main-screen]]
=== Main Screen

The image below shows the main window of Pl_Editor.

image::images/en/main_window.png[scaledwidth="95%"]

The left pane contains the list of basic items.

The right pane is the item settings editor.

<<<<<

[[main-window-toolbar]]
=== Main Window Toolbar

image:images/en/main_toolbar.png[]

The top toolbar allows for easy access to the following commands:

[width="100%",cols="28%,72%",]
|=======================================================================
|image:images/icons/new_page_layout.png[]
|Select the net list file to be processed.

|image:images/icons/open_page_layout.png[]
|Load a page layout description file.

|image:images/icons/save.png[]
|Save the current page layout description in a .kicad_wks file.

|image:images/icons/sheetset.png[]
|Display the page size selector and the title block user data editor.

|image:images/icons/print_button.png[]
|Prints the current page.

|image:images/icons/delete.png[]
|Delete the currently selected item.

|image:images/icons/undo.png[] image:images/icons/redo.png[]
|Undo/redo tools.

|image:images/icons/zoom_in.png[] image:images/icons/zoom_out.png[]
 image:images/icons/zoom_redraw.png[] image:images/icons/zoom_fit_in_page.png[] 
|Zoom in, out, redraw and auto, respectively.

|image:images/icons/pagelayout_normal_view_mode.png[]
|Show the page layout in user mode: texts are shown like in Eeschema or Pcbnew:
text format symbols are replaced by the user texts.

|image:images/icons/pagelayout_special_view_mode.png[]
|Show the page layout in native mode: texts are displayed "as is", with the
contained formats, without any replacement.

|image:images/en/set_base_corner.png[width="70%"]
|Reference corner selection, for coordinates displayed to the status bar.

|image:images/en/set_current_page.png[width="85%"]
|Selection of the page number (page & or other pages).

This selection has meaning only if some items than have a page option,
are not shown on all pages (in a schematic for instance, which contains
more than one page).

|=======================================================================

[[commands-in-drawing-area-draw-panel]]
=== Commands in drawing area (draw panel)

[[keyboard-commands]]
==== Keyboard Commands

[width="100%",cols="20%,80%",]
|==================================================================
|F1 |Zoom In
|F2 |Zoom Out
|F3 |Refresh Display
|F4 |Move cursor to center of display window
|Home |Fit footprint into display window
|Space Bar |Set relative coordinates to the current cursor position
|Right Arrow |Move cursor right one grid position
|Left Arrow |Move cursor left one grid position
|Up Arrow |Move cursor up one grid position
|Down Arrow |Move cursor down one grid position
|==================================================================

[[mouse-commands]]
==== Mouse Commands

[width="100%",cols="32%,68%",]
|============================================================
|Scroll Wheel |Zoom in and out at the current cursor position
|Ctrl + Scroll Wheel |Pan right and left
|Shift + Scroll Wheel |Pan up and down
|Right Button Click |Open context menu
|============================================================

[[context-menu]]
==== Context Menu

Displayed by right-clicking the mouse:

* Add Line

* Add Rectangle

* Add Text

* Append Page Layout Descr File

Are commands to add a basic layout item to the current page layout
description.

* Zoom selection: direct selection of the display zoom.

* Grid selection: direct selection of the grid.

[NOTE]
====
_Append Page Layout Descr File_ is intended to add poly polygons to make
logos.

Because usually a logo it needs hundred of vertices, you cannot create a
polygon by hand. But you can append a description file, created by
Bitmap2Component.
====


[[status-bar-information]]
=== Status Bar Information

The status bar is located at the bottom of the Pl_Editor and provides
useful information to the user.

image::images/en/pl_status_bar.png[scaledwidth="95%"]

Coordinates are *always relative to the corner* selected as
**reference**.

<<<<<

[[left-window]]
== Left window

The left windows shows the list of layout items.

One can select a given item (left clicking on the line) or, when right
clicking on the line, display a pop up menu.

This menu allows basic operations: add a new item, or delete the
selected item.

**-> A selected item is also drawn in a different color on draw panel**.

Design tree: the item 19 is selected, and shown in highlighted on the
draw panel.

image::images/en/project_tree.png[scaledwidth="40%"]

<<<<<

[[right-window]]
== Right window

The right window is the edit window.

[width="100%",cols="50%,50%",]
|=======================================================================
|image:images/en/property_none.png[width="50%"]
|image:images/en/property_main.png[width="50%"]
|=======================================================================

On this dialog you can set the page property and the item property of the
current item.

<<<<<

Displayed settings depend on the selected item:

[width="100%",cols="50%,50%",]
|=======================================================================
|Settings for lines and rectangles
|Settings for texts

|image:images/en/property_line.png[width="50%"]
|image:images/en/property_text.png[width="50%"]

|Settings for poly-polygons
|Setting for bitmaps

|image:images/en/property_polyline.png[width="50%"]
|image:images/en/property_bitmap.png[width="50%"]

|=======================================================================

<<<<<

[[interactive-edition]]
== Interactive edition

[[item-selection]]
=== Item selection

An item can be selected:

* From the Design tree.

* By Left clicking on it.

* By Right clicking on it (and a pop up menu will be displayed).

When selected, this item is drawn in yellow.

[width="100%",cols="50%,50%",]
|=======================================================================
|image:images/edit_line.png[width="70%"]
|The starting point (image:images/edit_line_start.png[])
and the ending point (image:images/edit_line_end.png[])
are highlighted.
|=======================================================================

When right clicking on the item, a pop-up menu is displayed.

The pop menu options slightly depend on the selection:

[width="100%",cols="34%,33%,33%",]
|=======================================================================
|image:images/en/context_line_move_start.png[width="50%"]
|image:images/en/context_line_move_end.png[width="50%"]
|image:images/en/context_line_move.png[width="50%"]
|=======================================================================

<<<<<

If more than one item is found, a menu clarification will be shown, to
select the item:

image::images/en/dialog_select_element.png[scaledwidth="50%"]

[width="100%",cols="50%,50%",]
|=======================================================================
|image:images/drag_element.png[width="70%"]
|Once selected, the item, or one of its end points, can be moved by
moving the mouse and placed (right clicking on the mouse).
|=======================================================================

<<<<<

[[item-creation]]
=== Item creation

To add a new item, right click the mouse button when the cursor is on
the left window or the draw area.

A popup menu is displayed:

Pop up menu in left window

image::images/en/context_createnew.png[scaledwidth="35%"]

Pop up menu in draw area.

image::images/en/context_createnew2.png[scaledwidth="35%"]


Lines, rectangles and texts are added just by clicking on the
corresponding menu item.

Logos must first be created by Bitmap2component, which creates a page
layout description file.

The Append Page Layout Descr File option append this file, to insert the
logo (a poly polygon).

<<<<<

[[adding-lines-rectangles-and-texts]]
=== Adding lines, rectangles and texts

When clicking on the option, a dialog is opened:

Adding line or rectangle

image::images/en/dialog_newline.png[scaledwidth="35%"]

Adding text

image::images/en/dialog_newtext.png[scaledwidth="35%"]


Position of end points, and corner reference can be defined here.

However they can be defined later, from the right window, or by moving
the item, or one of its end points.

Most of time the corner reference is the same for both points.

If this is not the case, define the corner reference at creation is
better, because if a corner reference is changed later, the geometry of
the item will be a bit strange.

When an item is created, if is put in move mode, and you can refine its
position (this is very useful for texts and small lines or rectangles)

[[adding-logos]]
=== Adding logos

To add a logo, a poly polygon (the vectored image of the logo) must be
first created using Bitmap2component.

Bitmap2component creates a page layout description file which is append
to the current design, using the *Append Page Layout Descr File* option.

Bitmap2component creates a page layout description file which contains
only one item: a poly polygon.

__However, this command can be used to append any page layout
description file, which is merged with the current design.__

Once a poly polygon is inserted, it can be moved and its parameters
edited.

[[adding-image-bitmaps]]
=== Adding image bitmaps

You can add an image bitmap using most of bitmap formats (PNG, JPEG, BMP
...).

* When a bitmap is imported, its PPI (pixel per inch) definition is set
  to 300PPI.

* This value can be modified in panel Properties (right panel).

* The actual size depend on this parameter.

* Be aware that using higher definition values brings larger output files,
  and can have a noticeable draw or plot time.

A bitmap can be repeated, **but not rotated**.