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

Discuss how to use the Ren'Py engine to create visual novels and story-based games. New releases are announced in this section.
Forum rules
This is the right place for Ren'Py help. Please ask one question per thread, use a descriptive subject like 'NotFound error in option.rpy' , and include all the relevant information - especially any relevant code and traceback messages. Use the code tag to format scripts.
Post Reply
Message
Author
rames44a
Newbie
Posts: 3
Joined: Sat May 12, 2018 11:48 am
Contact:

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

#1 Post by rames44a » Wed May 23, 2018 10:26 am

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
Miko-Class Veteran
Posts: 730
Joined: Fri Jun 24, 2016 5:58 pm
Contact:

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

#2 Post by kivik » Wed May 23, 2018 10:55 am

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
Newbie
Posts: 3
Joined: Sat May 12, 2018 11:48 am
Contact:

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

#3 Post by rames44a » Wed May 23, 2018 11:38 am

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
Miko-Class Veteran
Posts: 730
Joined: Fri Jun 24, 2016 5:58 pm
Contact:

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

#4 Post by kivik » Wed May 23, 2018 11:46 am

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?

Post Reply

Who is online

Users browsing this forum: No registered users