Meaning of setPen(const QPen & pen), and copying of QPen.
Doesn't this mean that the setPen method is guaranteed (by the compiler) not to change the passed parameter? But you can pass a reference to a QPen that is not constant?
The documentation for setPen() says "Sets the item's pen to pen. ...". Shouldn't it say more? For example, that "it copies pen and doesn't store a reference to pen. You can subsequently alter the passed pen and it will have no effect on the graphic item's appearance."
Also, in PySide I tried "pencopy = copy.deepCopy(pen)" and it failed later with "Internal C++ object (PySide.QtGui.QPen) already deleted." I'm OK with that, but shouldn't the documentation emphasize that there is a specific copy constructor: QPen(pen).
What is a good metaphor for how to use QPen and the like? A template to be constructed on the fly and used just to setPen(), not as a hook into a graphic item?
There's no need to spell that out because it is not possible.
The setPen() routine could initialise a local const reference to the pen but that reference will be destroyed before the routine returns, and the referenced object cannot disappear during that time, so this poses no problem. The function cannot store a reference in a member variable because that member variable must be initialised at object construction and forever refers to the object it was initialised to: i.e. it cannot later refer to another object. Assigning to a reference variable changes the value of the object referred to, it does not make the reference refer to a different object. To hold on to the QPen the function must make a copy.
The documentation clearly indicates that there is a public QPen copy constructor.
bq. QPen::QPen ( const QPen & pen )
Constructs a pen that is a copy of the given pen
Thanks for clarifying C++ semantics for references. I knew that, but have forgotten it, and hope to forget it again.
I get confused because I am writing in Python but reading documentation for C++. In Python, a 'reference' is different. There are no variables, just names, and many names can reference the same object.
Your answer that 'its not necessary' is technically accurate since if a reader is familiar with C++ semantics they can reason (as you show) that setPen MUST copy the QPen object (or its attributes.)
But for simplicity and clarity (so that every reader does not need to reason about it) the documentation could say more about the objects, irrespective of the C++ semantics. "setPen" is confusing because set often means 'assign' but as you pointed out, you can't assign a reference. "Copy" might be better, but also might be too abstract because you might need to think about deep copy if you didn't know that QPen is just a set of non-reference objects (called expanded in some languages.)
Thats why I was looking for a better metaphor such as template or stamp.
Why not: "setPen stamps the graphic item with the attributes of the QPen?"
Or "a QPen is an instrument that can be loaded with attributes such as color, and reloaded, but when setPen on a graphic item, a QPen is cloned, and the clone is thereafter immutable, but the pen of the graphics item can be setPen again with a different QPen. When a QPen is passed to a QPainter, it is used, but not cloned."