Fabric Wiki

User Tools

Site Tools

Trace:
tutorial:screen

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tutorial:screen [2023/04/21 10:22] – [Notice about the order] solidblocktutorial:screen [2026/03/01 23:33] (current) – cassiancc
Line 1: Line 1:
 ====== Creating a screen ====== ====== Creating a screen ======
  
-:!: The page is still in progress.+A **screen** is a graphical user interface that extends ''Screen'', allowing the user to interact and fulfill some functionalities. One example of a screen is a custom config screen of your mod. Screens only exist in the client, so if you are using split sources, make sure to place it in your `client` source set.
  
-A **screen** is a graphical user interface that extends ''Screen'', allowing the user to interact and fulfill some functionalities. One example of a screen is a custom config screen of your mod. Screens only exist in the client, so you must annotate them with ''@Environment(EnvType.CLIENT)''. +You may use mixins to add into an existing screen a button that goes to your screen. But in many cases, we can implement the ''ModMenuApi'' of [[https://modrinth.com/mod/modmenu|Mod Menu]] mod, and make it possible to access the screen via the config button in the Mod Menu screen. This article does document how to implement ''ModMenuApi''.
- +
-You may use mixins to add into an existing screen a button that goes to your screen. But in many cases, we can implement the ''ModMenuApi'' of Mod Menu mod, and make it possible to access the screen via the config button in the Mod Menu screen. This article does document how to implement ''ModMenuApi''.+
  
 ===== Adding widgets ===== ===== Adding widgets =====
Line 11: Line 9:
  
 <code java> <code java>
-@Environment(EnvType.CLIENT) 
 public class TutorialScreen extends Screen { public class TutorialScreen extends Screen {
   protected TutorialScreen() {   protected TutorialScreen() {
     // The parameter is the title of the screen,     // The parameter is the title of the screen,
     // which will be narrated when you enter the screen.     // which will be narrated when you enter the screen.
-    super(Text.literal("My tutorial screen"));+    super(Component.literal("My tutorial screen"));
   }   }
  
  
-  public ButtonWidget button1; +  public Button button1; 
-  public ButtonWidget button2;+  public Button button2;
  
   @Override   @Override
   protected void init() {   protected void init() {
-    button1 = ButtonWidget.builder(Text.literal("Button 1"), button -> {+    button1 = ButtonWidget.builder(Component.literal("Button 1"), button -> {
       System.out.println("You clicked button1!");       System.out.println("You clicked button1!");
     })     })
-        .dimensions(width / 2 - 205, 20, 200, 20) +        .bounds(width / 2 - 205, 20, 200, 20) 
-        .tooltip(Tooltip.of(Text.literal("Tooltip of button1")))+        .tooltip(Tooltip.create(Component.literal("Tooltip of button1")))
         .build();         .build();
     button2 = ButtonWidget.builder(Text.literal("Button 2"), button -> {     button2 = ButtonWidget.builder(Text.literal("Button 2"), button -> {
       System.out.println("You clicked button2!");       System.out.println("You clicked button2!");
     })     })
-        .dimensions(width / 2 + 5, 20, 200, 20) +        .bounds(width / 2 + 5, 20, 200, 20) 
-        .tooltip(Tooltip.of(Text.literal("Tooltip of button2")))+        .tooltip(Tooltip.create(Component.literal("Tooltip of button2")))
         .build();         .build();
          
-    addDrawableChild(button1); +    addRenderableWidget(button1); 
-    addDrawableChild(button2);+    addRenderableWidget(button2);
   }   }
 } }
Line 50: Line 47:
   * The screen is resized. Before invoking this, all existing elements are removed.   * The screen is resized. Before invoking this, all existing elements are removed.
  
-You must use add the elements to the screen via using ''addDrawable'', ''addSelectableChild'' or ''addDrawableChild''. The difference is: +You must use add the elements to the screen via using ''addRenderableOnly'', ''addWidget'' or ''addRenderableWidget''. The difference is: 
-  * ''addDrawable'': The element will be rendered, but you cannot select it, either by using mouse or keyboard. +  * ''addRenderableOnly'': The element will be rendered, but you cannot select it, either by using mouse or keyboard. 
-  * ''addSelectableChild'': You can select and interact it, but it will not be rendered. +  * ''addWidget'': You can select and interact it, but it will not be rendered. 
-  * ''addDrawableChild'': The element will be both rendered and interactable, which is the most common case.+  * ''addRenderableWidget'': The element will be both rendered and interactable, which is the most common case.
  
-In the ''ButtonWidget.builder(...).builder()'', you can specify the size and position of the button by using ''size'' and ''position'' respectively, or directly using ''dimensions''. The ''tooltip'' specifies the tooltip, which will be rendered and narrated when your mouse hovers on, or use Tab to focus on it. ''Tooltip.of'' takes two arguments, the first to be shown, and the second (optional) to be narrated.+In the ''Button.builder(...).builder()'', you can specify the size and position of the button by using ''size'' and ''pos'' respectively, or directly using ''bounds''. The ''tooltip'' specifies the tooltip, which will be rendered and narrated when your mouse hovers on, or use Tab to focus on it. ''Tooltip.create'' takes two arguments, the first to be shown, and the second (optional) to be narrated.
  
-For versions before 1.19.3, ''ButtonWidget.builder(...)'' does not exist. In that case, please directly invoke the constructor of ''ButtonWidget''.+For versions before 1.19.3, ''Button.builder(...)'' does not exist. In that case, please directly invoke the constructor of ''Button''.
  
 ==== Can I instantiate widgets in the constructor ==== ==== Can I instantiate widgets in the constructor ====
Line 67: Line 64:
   @Override   @Override
   protected void init() {   protected void init() {
-    addDrawableChild(button1); +    addRenderableWidget(button1); 
-    addDrawableChild(button2);+    addRenderableWidget(button2);
   }   }
 </code> </code>
  
-This is also OK. Its advantage is, if the widgets have some several states (such as the current selections of ''CyclingWidget'', or typed text in the ''TextFieldWidget''), they will not be reset when you resize the screen, because they will not be created again. However, when resizing, the ''width'' and ''height'' of screen are changed, but the positions and sizes of elements will not update. Therefore, in this case, you have to update the sizes or positions in the ''init'' method.+This is also OK. Its advantage is, if the widgets have some several states (such as the current selections of ''CycleButton'', or typed text in the ''EditBox''), they will not be reset when you resize the screen, because they will not be created again. However, when resizing, the ''width'' and ''height'' of screen are changed, but the positions and sizes of elements will not update. Therefore, in this case, you have to update the sizes or positions in the ''init'' method.
  
 <code java> <code java>
Line 80: Line 77:
     button2.setPosition(width / 2 + 5, 20);     button2.setPosition(width / 2 + 5, 20);
  
-    addDrawableChild(button1); +    addRenderableWidget(button1); 
-    addDrawableChild(button2)+    addRenderableWidget(button2)
   }   }
 </code> </code>
Line 89: Line 86:
  
 ===== The parent screen ===== ===== The parent screen =====
-I accessed the screen via another screen, such as the Mod Menu screen, but when I press ''Esc'' to go back, it just jumped to the main screen, not the previous screen, why? This is because you did not specify a parent screen, and the ''close'' method just directly jumps to the main screen.+I accessed the screen via another screen, such as the Mod Menu screen, but when I press "Esc" to go back, it just jumped to the main screen, not the previous screen, why?
  
-Add a parent as a parameter and field, and use it in the ''close'' method:+This is because you did not specify a parent screen, and the ''close'' method just directly jumps to the main screen. 
 + 
 +Add a ''parent'' as a parameter and field, and use it in the ''close'' method:
 <code java> <code java>
  
Line 97: Line 96:
  
   protected TutorialScreen(Screen parent) {   protected TutorialScreen(Screen parent) {
-    super(Text.literal("My tutorial screen"));+    super(Component.literal("My tutorial screen"));
     this.parent = parent;     this.parent = parent;
   }   }
      
   @Override   @Override
-  public void close() {+  public void onClose() {
     client.setScreen(parent);     client.setScreen(parent);
   }   }
Line 108: Line 107:
  
 ===== Add narrations ===== ===== Add narrations =====
-By default, when narration is enabled, the screen title and information of the element you hover or focus on will be narrated. If the screen requires extra narrations (for example it has some texts rendered but not added as a widget), you can override ''addScreenNarrations'' or ''addElementNarrations''. The methods take a ''NarrationBuilder'', in which you can use ''add'' method to add narration messages. The narration messages are divided into the following parts (''NarrationPart''):+By default, when narration is enabled, the screen title and information of the element you hover or focus on will be narrated. If the screen requires extra narrations (for example it has some texts rendered but not added as a widget), you can override ''updateNarrationState'' or ''updateNarratedWidget''. The methods take a ''NarrationElementOutput'', in which you can use ''add'' method to add narration messages. The narration messages are divided into the following parts (''NarratedElementType''):
  
   * **Title**: The title of the screen, which is defined in the constructor. When you enter the screen, the title will be automatically narrated.   * **Title**: The title of the screen, which is defined in the constructor. When you enter the screen, the title will be automatically narrated.
   * **Position**: Telling you the position of the widget you are focusing on. In vanilla, it is: "//Screen element %s out of %s//". Besides, if in a list widget, the following will also be narrated: "//Selected list row %s out of %s//".   * **Position**: Telling you the position of the widget you are focusing on. In vanilla, it is: "//Screen element %s out of %s//". Besides, if in a list widget, the following will also be narrated: "//Selected list row %s out of %s//".
-  * **Hint**: This refers the tooltip of the element you focus on or hovers on. For example, the ''tooltip'' method when you create the ''ButtonWidget'' in the code above.+  * **Hint**: This refers the tooltip of the element you focus on or hovers on. For example, you may remember about the ''tooltip'' method when you create the ''Button'' in the code above. The tooltip is narrated in this part.
   * **Usage**: In vanilla, the usage is: "//Use mouse cursor or Tab button to select element//".   * **Usage**: In vanilla, the usage is: "//Use mouse cursor or Tab button to select element//".
  
 Besides the narration of the screen, you can also customize the narration of the element, by overriding ''appendNarrations'' method of the class of that element. The element is narrated after the narration of the screen. Besides the narration of the screen, you can also customize the narration of the element, by overriding ''appendNarrations'' method of the class of that element. The element is narrated after the narration of the screen.
  
-In the method of appending narrations, using ''narrationBuilder.nextMessage()'' can append narrations after the current narrations, instead of replacing existing part of the narration.+In the method of appending narrations, using ''narrationBuilder.nest()'' can append narrations after the current narrations, instead of replacing existing part of the narration.
  
-In some cases, you want repetitive narrations, instead of narrating only once. For example, when loading a level, the percentage of loading is narrated repetitively, telling the user the current loading status. You can call ''narrateScreenIfNarrationEnabled'' in the ''render'' or ''tick'' method. For more details, you may refer to sources of ''LevelLoadingScreen''.+In some cases, you want repetitive narrations, instead of narrating only once. For example, when loading a level, the percentage of loading is narrated repetitively, telling the user the current loading status. You can call ''notifyListUpdated'' in the ''render'' or ''tick'' method. For more details, you may refer to sources of ''LevelLoadingScreen''.
  
 ===== Adding text ===== ===== Adding text =====
-In ''render'' method, you can invoke methods like ''textRenderer.draw'', ''drawTextWithShadow'' or ''drawCenteredTextWithShadow'' to render a text on the screen.+In ''render'' method, you can invoke methods like ''font.draw'', ''drawString'' or ''drawCenteredString'' to render a text on the screen.
 <code java> <code java>
 +  // For versions 1.20 below
   @Override   @Override
-  public void render(MatrixStack matrices, int mouseX, int mouseY, float delta) {+  public void render(PoseStack matrices, int mouseX, int mouseY, float delta) {
     super.render(matrices, mouseX, mouseY, delta);     super.render(matrices, mouseX, mouseY, delta);
-    drawCenteredTextWithShadow(matrices, textRenderer, Text.literal("You must see me"), width / 2, height / 2, 0xffffff);+    drawCenteredString(matrices, textRenderer, Component.literal("You must see me"), width / 2, height / 2, 0xffffff); 
 +  } 
 +   
 +  // For versions 1.20 and after 
 +  @Override 
 +  public void render(GuiGraphics context, int mouseX, int mouseY, float delta) { 
 +    super.render(context, mouseX, mouseY, delta); 
 +    context.drawCenteredString(font, Component.literal("You must see me"), width / 2, height / 2, 0xffffff);
   }   }
 </code> </code>
Line 133: Line 140:
 If you're concerned that the text can be pretty long and may exceed the screen limit, you can use ''MultilineText'' so it can be wrapped smartly. If you're concerned that the text can be pretty long and may exceed the screen limit, you can use ''MultilineText'' so it can be wrapped smartly.
 <code java> <code java>
-    final MultilineText multilineText = MultilineText.create(textRenderer, Text.literal("The text is pretty long ".repeat(20)), width - 20); +    final MultiLineLabel multilineText = MultiLineLabel.create(textRenderer, Component.literal("The text is pretty long ".repeat(20)), width - 20); 
-    multilineText.drawWithShadow(matrices, 10, height / 2, 16, 0xffffff);+     
 +    // For versions 1.20 below 
 +    multilineText.renderLeftAligned(matrices, 10, height / 2, 16, 0xffffff); 
 +    // For versions 1.20 and after 
 +    multilineText.renderLeftAligned(context, 10, height / 2, 16, 0xffffff);
 </code> </code>
  
-Another alterative is using ''TextWidget'' or ''MultilineTextWidget''. They are by default not selectable or narratable because their ''active'' field is ''false''.+Another alterative is using ''StringWidget'' or ''MultilineTextWidget''. They are by default not selectable or narratable because their ''active'' field is ''false''. 
 + 
 +===== Scrolling ===== 
 +The screen does not support scrolling, but you can add widgets that supports scrolling. ''AbstractSelectionList'' is a class for widgets that contains multiple entries and supports scrolling. However, instead of directly extending it, it is more suitable to extend ''ObjectSelectionList'' or ''ContainerObjectSelectionList'', which already implemented navigation and narration. The difference is: 
 + 
 +  * ''ObjectSelectionList'' refers to a widget in which you can select a row. In widgets that extends the class, you usually select one entry in the list. Some vanilla examples are biome selection screen in the buffet (single biome) world option, and the language selection screen. 
 +  * ''ContainerObjectSelectionList'' refers to a widget where each row has child elements. In widgets that extends this class, you select and interacts the elements in the rows. Like a ''Screen'', the ''ContainerObjectSelectionList.Entry'' should have zero, one, or more child elements. 
 + 
 +===== Things to check before finishing =====
  
-[WIP]+After finishing your screen, in order to avoid potential issues, please check: 
 +  * whether the screen returns to the last screen (parent screen) when you press "Esc" 
 +  * whether these classes exist only on client (which means they will not be loaded in the dedicated server) 
 +  * whether elements are focused in the correct order when you press "Tab" to select them 
 +  * whether the behaviors are correct when you resize 
 +  * whether the narrations are correct when you use "Tab" or mouse cursor to select element while narration enabled
tutorial/screen.1682072550.txt.gz · Last modified: 2023/04/21 10:22 by solidblock