diff --git a/src/pl_editor/pl_editor.adoc b/src/pl_editor/pl_editor.adoc index d27a65ac..b391bfca 100644 --- a/src/pl_editor/pl_editor.adoc +++ b/src/pl_editor/pl_editor.adoc @@ -42,7 +42,7 @@ may 23, 2015. <<<<< [[introduction-to-pl_editor]] -== Introduction to *Pl_Editor* +== Introduction Pl_Editor is a page layout editor tool to create custom title blocks, and frame references. @@ -50,39 +50,11 @@ 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 +An internal default page layout description to display the default +KiCad title block is used until a file is read. The current page layout description can be written in a **.kicad_wks* file, using the S-expression format, which is widely used in KiCad. @@ -90,22 +62,21 @@ 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 +Pl_Editor is typically invoked from a command line, or from the KiCad +manager. -[[basic-page-layout-items-properties]] -=== Basic page layout items properties: +From a command line, the syntax is pl_editor <*.kicad_wks file to open>. +[[basic-layout-elements]] +=== Basic layout elements 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. +* *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). These poly polygons are created by **Bitmap2component**, and cannot be @@ -114,7 +85,9 @@ Basic page layout items are: * *Bitmaps* to place logos. -WARNING: Bitmaps can be plotted only by few plotters: PDF and PS only. +WARNING: Bitmaps can be plotted only by few plotters (PDF and +PS only) Therefore, for other plotters, only a bounding box will be +plotted. Therefore: @@ -130,8 +103,8 @@ 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 +[[coordinates-definition-reference-corners]] +=== Coordinates defintion and reference corners Each position, start point and end point of items is always relative to a page corner. @@ -139,9 +112,7 @@ 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: - +Reference corners: image:images/en/page_property_1.png[] * When the page size is changed, the position of the item, relative to @@ -155,224 +126,11 @@ 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 +[[pl_editor-interface]] +== Interface [[main-screen]] -=== Main Screen +=== Main window The image below shows the main window of Pl_Editor. @@ -385,7 +143,7 @@ The right pane is the item settings editor. <<<<< [[main-window-toolbar]] -=== Main Window Toolbar +=== Main toolbar image:images/en/main_toolbar.png[] @@ -433,75 +191,14 @@ contained formats, without any replacement. |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. -==== +are not shown on all pages (in a schematic for instance, which contains +more than one page). + +|======================================================================= [[status-bar-information]] -=== Status Bar Information +=== Status bar The status bar is located at the bottom of the Pl_Editor and provides useful information to the user. @@ -514,7 +211,7 @@ Coordinates are *always relative to the corner* selected as <<<<< [[left-window]] -== Left window +=== Left window The left windows shows the list of layout items. @@ -534,7 +231,7 @@ image::images/en/project_tree.png[scaledwidth="40%"] <<<<< [[right-window]] -== Right window +=== Right window The right window is the edit window. @@ -569,8 +266,63 @@ Displayed settings depend on the selected item: <<<<< -[[interactive-edition]] -== Interactive edition +[[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. +==== [[item-selection]] === Item selection @@ -620,8 +372,8 @@ moving the mouse and placed (right clicking on the mouse). <<<<< -[[item-creation]] -=== Item creation +[[adding-elements]] +== Adding elements To add a new item, right click the mouse button when the cursor is on the left window or the draw area. @@ -646,22 +398,13 @@ 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 +[[adding-lines-rectangles]] +=== Adding lines and rectangles 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 @@ -676,6 +419,182 @@ 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-text]] +=== Adding text + +Text is created nearly the same as lines and rectangles: + +image::images/en/dialog_newtext.png[scaledwidth="35%"] + +[[page-1-text]] +==== Page 1 text + +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. + +<<<<< + +[[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 text + +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%"] + +<<<<< + +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[] + +<<<<< + +[[text-full-size-constraint]] +==== Full-size text + +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[] + +<<<<< + [[adding-logos]] === Adding logos @@ -711,3 +630,29 @@ You can add an image bitmap using most of bitmap formats (PNG, JPEG, BMP and can have a noticeable draw or plot time. A bitmap can be repeated, **but not rotated**. + + +[[rotation]] +=== Rotating elements + +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]] +=== Repeating elements + +Items can be repeated: + +This is useful to create grid and grid labels. + +image::images/en/page_property_2.png[scaledwidth="95%"]