SetLayer(), TEXTE_PCB and Python bindings doc puzzles

[gwideman]

Summary:

• Where are the constants or at least the values defined for PCB_LAYER_ID
• Where is TEXTE_PCB in the Doxygen doc, and if it’s not there, why, and in that case also how does it work anyway?

Details

I am writing a script to run in the PCBNew console to add some text to a board, using the following code:
import pcbnew
pcb = pcbnew.GetBoard()
[…]
txt = pcbnew.TEXTE_PCB(pcb)
txt.SetText(“Hello”)
txt.SetPosition(pcbnew.wxPoint(mm_to_nm(40), mm_to_nm(20) ))
txt.SetHorizJustify(pcbnew.GR_TEXT_HJUSTIFY_CENTER)
txt.SetTextSize(pcbnew.wxSize(mm_to_nm(10), mm_to_nm(10) ))
txt.SetThickness(mm_to_nm(1) )
pcb.Add(txt)
pcbnew.Refresh()

So far so good. But I want to set it to a particular layer, which probably involves txt.SetLayer(aLayer) where aLayer is evidently of type PCB_LAYER_ID.

Trouble is, I can’t find any docs on what the PCB_LAYER_ID type is. It may well be an enum, and possibly just accepts integers. But where are those integers defined, or where are constants defined for them?

Which leads me to the puzzle about the Doxygen API docs at
https://docs.kicad.org/doxygen-python/

I can’t find any definition of PCB_LAYER_ID, nor for that matter (and more disturbingly) TEXTE_PCB. Yet strangely the code above with TEXTE_PCB in it does work.

I’m pretty sure TEXTE_PCB should be a class in namespace pcbnew, and pcbnew.TEXTE_PCB() is an initializer. But looking it up that way I don’t find it. And it also does not appear in the source code that the docs refer to at https://docs.kicad.org/doxygen-python/pcbnew_8py_source.html

So I’m at bit confused. I might suspect that the docs are out of sync with actual shipping kicad’s API (I have the latest Kicad 5.1.9 installed). But if that was the case how does pcbnew.TEXTE_PCB(pcb) work? Does the API have dynamic dispatching for functions it doesn’t have pre-connected?

[qu1ck]

You are probably using 5.1 while the docs are for current master branch. TEXTE_PCB was renamed to PCB_TEXT in next version.
I don’t know if there is a link for 5.1 doxygen docs.
Layers are defined here https://gitlab.com/kicad/code/kicad/-/blob/5.1/include/layers_id_colors_and_visibility.h#L73 you can access them directly like pcbnew.B_Cu

Easy way to inspect api for the version you have is to open scripting console, import pcbnew and look at it in inspector tools.

[gwideman]

@qu1ck Great info, thanks!

[MitjaN]

5.1 documentation: https://kicad-downloads.s3.cern.ch/doxygen-python/namespacepcbnew.html
5.99 documentation https://docs.kicad.org/doxygen-python/namespacepcbnew.html

[der.ule]

It would actually be nicer if KiCAD’s version was included in the URL.

https://docs.kicad.org/doxygen-python/v5_1/namespacepcbnew.html
https://docs.kicad.org/doxygen-python/v6_0/namespacepcbnew.html
.
.
etc.

[Mike_Lemon]

Defiantly or atleast have a small article somewhere highlighting some differences or the direction forwards with the development.

[craftyjon]

While that would be nice, the “5.99 documentation” link is not to a stable, fixed version: it’s to the latest documentation, built from daily changes. There is no stable 6.0 API yet. Once there is, versioned documentation for it would be possible.

[gwideman]

To me it would seem rather essential that the docs have some indication written into the page, like in the title, that tells what version they are for.

I should point out that the current official doc for PCBNew scripting of the official shipping version, v5.1 (https://docs.kicad.org/5.1/en/pcbnew/pcbnew.html section “KiCad Scripting Reference”) has a link " Also see the doxygen documentation on Python Scripting Reference that points to http://docs.kicad.org/doxygen-python/namespaces.html which redirects to https://docs.kicad.org/doxygen-python/namespaces.html, the 5.99 API docs.

So basically the KiCad 5.1 docs are deliberately misleading script writers to the wrong docs, which are then not marked as to version, so there’s no way for the script writers to know they are barking up the wrong red herring.

I certainly concur that having it in the URL would be nice, if the current hosts for the docs allow that. But if they are on different servers and/or the paths are not particularly coordinated with the versions, then at least for &^%$'s sake let’s have the version number on the doc pages – that’s surely just a small edit to a template somewhere. This would immediately relieve all API docs users from wild goose chases.

Of course – all thanks to volunteers who are putting in hard work to get KiCad where it is, and where it’s going. This small incremental effort would help realize that good work, and also allow others to build on the foundation and make KiCad even better.