undocumented Processing stuff

[villares]

For instance... Processing has an undocumented link() function, well, there is an example for it...

Should we add it to py5 or may be not? If we do add it, it could be like this:

def link(url, new=0, autoraise=True):
    """
    Display url using the default browser. If new is 0, the url is opened in the same browser window if possible.
    If new is 1, a     new browser window is opened if possible.
    If new is 2, a new browser page (“tab”) is opened if possible.
    If autoraise is True, the window is raised if possible (note that under many window managers this will occur
    regardless of the setting of this variable).
    """
    import webbrowser
    webbrowser.open(url, new, autoraise)

https://docs.python.org/3/library/webbrowser.html

This is how I ported the example for now:
https://github.com/villares/py5examples/blob/processing-python-mode-examples/examples-from-Processing-Python-mode/Basics/Web/EmbeddedLinks/EmbeddedLinks.py

[hx2A]

I suspect the undocumented link() method is from Processing's Java Applet days, when it would run in a browser. We could add a link() method to py5. Thanks for writing the code for it. Would you like for me to show you how to make a PR to add this? Because of the metaprogramming stuff there's more to it than just adding a single method to a class, but it isn't overly complicated.

[villares]

Yeah, I'd like to learn how to do it. But in this particular case I think we might skip adding it, just steer people to webbrowser module in the examples and that's it...

[hx2A]

I think you are right. Using Python's webbrowser library is simple and easy to use, so we can just use that in the examples.

[villares]

Other undocumented features/fields:

g._instance.strokeColor current stroke color
g._instance.fillColor current fill color

[hx2A]

There is also smooth, colorMode, tintColor, strokeWeight, strokeJoin, strokeCap, rectMode, ellipseMode, shapeMode, imageMode, textFont, textAlign, ... the list goes on. There are dozens public variables in PGraphics that could turn into fields in py5.Py5Graphics. But should they? If you set the stroke color to something, don't you already know what the stroke color is? Same thing for the other variables in that list. How does it add value to have a field to provide this information? I don't see it, but if you do, can you help me see it?

[villares]

For strokeColor this is the use case:

When you want to build a function that will draw stuff that have parts that follows the current stroke color, and in some cases it might need to keep the fill color independent for other parts (like some text, for instance). I think I have used fillColor too, and wanted to use strokeWeight but didn't, and I couldn't find the example/code where I would use it. The last time I looked into it I couldn't reach the strokeWeight field in _instance :(

[hx2A]

I see what you are doing and how it could be helpful. But for your example, couldn't you replace fill(g._instance.strokeColor) with fill(0, 150, 0)? The color is hard coded in setup(), so why not hard code it in seta_vetor() also?

I'm not opposed to adding g.stroke_color and g.fill_color, but I do think it's a bad idea add every public variable in PGraphics as a field in py5.Py5Graphics. Would you be interesting in making a PR for this? There are a couple of steps mostly related to the example code and reference docs.

[villares]

I do agree it would be a bad idea to expose every public variable in PGraphics.

As I tried to explain, not very well, I might like to have arrows of several different colors in the same drawing, then, in this case one could call stroke(0, 150, 0); fill(0, 150, 0) before a green arrow and then stroke(0, 0, 150); fill(0, 0, 150) before a blue arrow. But for more complex annotative symbols it would be nice to keep the current fill color for other internal elements, say, this vector-arrow representation could have a white (or current fill) text for showing the magnitude value...

It is such a rare case, and then, again, another solution, the function could have keyword arguments for a separate fill, etc...

There is too much stuff in my plate right now...

My suggestion: This could be in a nice doc page/example/tutorial explaining g and g._instance for advanced users. In other words, the only thing we should change is that this stuff should not be completely undocumented. And that would be enough!

[hx2A]

OK, I see what you are saying. There is always a workaround, including such things as creating your own variable to store the current fill and stroke colors, but then you're kind of duplicating what g._instance.fillColor, etc is already doing for you. It would be convenient in some cases to not have to do that.

My suggestion: This could be in a nice doc page/example/tutorial explaining g and g._instance for advanced users. In other words, the only thing we should change is that this stuff should not be completely undocumented. And that would be enough!

I am behind on writing documentation but I am writing this morning. The ._instance stuff will be included when I talk about how py5 actually works.