'hide screen' vs 'renpy.hide_screen()' - documentation inconsistency?

[rames44a]

https://www.renpy.org/doc/html/screens.html#show-screen describes the show screen and hide screen statements.

show screen is explicitly documented as taking a screen name as an argument, which makes perfect sense. hide screen just says "The hide screen statement is used to hide a screen that is currently being shown," without explicitly documenting what argument it takes. The examples shown match the examples in the show screen documentation, which are screen names, thus leading one to believe that it takes a screen name as well.

However, https://www.renpy.org/doc/html/screen_p ... -functions documents the renpy.hide_screen() function, which says "The programmatic equivalent of the hide screen statement.", and specifies that it takes a tag. ("Hides the screen with tag on layer.") No mention is made of it accepting a screen name.

So my questions are: -

• Will renpy.hide_screen() take a screen name? Or only a tag?

• Does the hide screen statement only take a screen name? Or can it take a tag?

• If hide screen will take a tag, what's the syntax in that case?

• If they can take either a tag or a screen name, how does Ren'py distinguish whether a tag or a screen name is intended?

[kivik]

You can test this out yourself by creating two screens and test out different scenarios - in fact that's probably the best way for you to understand what's going to happen.

I just did that and my conclusion is, it takes the tag name in both cases - and if a screen doesn't have a tag name, the screen name is treated as tag name.

Therefore:

Code: Select all

screen test:
    pass # has tag name "test"

screen test1:
    tag test # has tag name "test"

screen test2:
    tag test1 # has tag name "test1"

In the above, screens test and test1 share the same tag: test. screen test2 has tag name test1. So hide screen test1 will hide screen test2 and not screen test1.

Again, write your own code and experiment so you understand fully what's going on.

[rames44a]

Thanks.

I was working on doing just that when I posted the question, however part of the point is that when one strays away from what is explicitly documented, one is potentially subject to, well, “undocumented behavior” which may be unintentional or subject to change. Thus, if this is the intended behavior, then the documentation on the statement is incomplete in not mentioning tags, and the documentation on the function is technically incorrect in stating that it takes a tag (and implicit, only a tag.)

No criticism intended - far from it. But a potential for improvement.

[kivik]

Yeah there're definitely a few things wrong with the documentation - I think that's the trouble when PyTom's doing that alone, along with updating the engine etc. Not sure how best to report it, maybe on the Development forum?