Merge pull request #388 from MyreMylar/document-text-entry-box

Add basic documentation for text entry box

docs/source/theme_guide.rst

@@ -482,6 +482,7 @@ Theme Options Per Element
     theme_reference/theme_selection_list
     theme_reference/theme_status_bar
     theme_reference/theme_text_box
+    theme_reference/theme_text_entry_box
     theme_reference/theme_text_entry_line
     theme_reference/theme_tooltip
     theme_reference/theme_vertical_scroll_bar

docs/source/theme_reference/theme_text_entry_box.rst

@@ -0,0 +1,110 @@
+.. _theme-text-box:
+
+UITextEntryBox Theming Parameters
+===============================
+
+.. raw:: html
+
+    <video width="220" height="220" nocontrols playsinline autoplay muted loop>
+        <source src="../_static/text_box.mp4" type="video/mp4">
+        Your browser does not support the video tag.
+    </video>
+
+The :class:`UITextEntryBox <pygame_gui.elements.UITextEntryBox>` theming block id is 'text_entry_box'.
+
+Colours
+-------
+
+.. figure:: ../_static/text_box_colour_parameters.png
+
+   A diagram of which part of the element is themed by which colour parameter. This correspondence is the same for the
+   parameters named for the different link states e.g. the parameter 'link_hover' themes the same text as 'link_text'
+   when the link is in the hovered state.
+
+:class:`UITextEntryBox <pygame_gui.elements.UITextEntryBox>` makes use of these colour parameters in a 'colours' block. All of these colours can
+also be a colour gradient:
+
+ - "**dark_bg**" -  The background colour/gradient of the text box element.
+ - "**normal_border**" - The colour/gradient of the border around the text box element.
+ - "**link_text**" - The default colour/gradient of any links in the text.
+ - "**link_hover**" - The colour/gradient of link text when we hover over it with the mouse.
+ - "**link_selected**" - The colour/gradient of link text when they are clicked on with the mouse.
+
+Misc
+----
+
+:class:`UITextEntryBox <pygame_gui.elements.UITextEntryBox>` accepts the following miscellaneous parameters in a 'misc' block:
+
+ - "**shape**" - Can be one of 'rectangle' or 'rounded_rectangle'. Different shapes for this UI element.
+ - "**shape_corner_radius**" - Only used if our shape is 'rounded_rectangle'. It sets the radius used for the rounded corners.
+ - "**border_width**" - The width of the border around the element in pixels. Defaults to "1".
+ - "**shadow_width**" - The width of the shadow around the element in pixels. Defaults to "2".
+ - "**padding**" - the horizontal and vertical 'padding' between the border and where we render the text. Defaults to "5,5".
+ - "**link_normal_underline**" - Set to either "1" or "0". Whether link text is normally underlined. Defaults to "0" (False).
+ - "**link_hover_underline**" - Set to either "1" or "0". Whether link text is underlined when they are hovered over with the mouse. Defaults to "1" (True).
+ - "**text_horiz_alignment**" - Set to "default, "left", "right" or "center". Controls the horizontal placement of all the text box text. Default is "default" which will use any in-text alignment set, all other values will override any in-text formatting.
+ - "**text_vert_alignment**" - Set to "default", "top", "bottom or "center". Controls the vertical placement of the text box text. Default is "default" which will use any in-text alignment set, all other values will override any in-text formatting.
+ - "**text_horiz_alignment_padding**" - If horizontal alignment is set to 'left' or 'right' this value will control the buffer between the edge of the box padding and where we start placing the text. Default is "0". Using "padding" is better but these parameters are included for completeness.
+ - "**text_vert_alignment_padding**" - If vertical alignment is set to 'top' or 'bottom' this value will control the buffer between the edge of the box padding and where we start placing the text. Default is "0". Using "padding" is better but these parameters are included for completeness.
+ - "**line_spacing**" - Sets the spacing of lines of text. The default is 1.25.
+
+Sub-elements
+--------------
+
+The text entry box may also contain a :class:`UIVerticalScrollBar <pygame_gui.elements.UIVerticalScrollBar>` which you can reference with the block id
+'text_entry_box.vertical_scroll_bar'. You can also reference all of the buttons that are sub elements of the
+scroll bar with a theming block id of 'text_entry_box.vertical_scroll_bar.button'.
+
+You can further reference the individual buttons of the scroll bar by adding their object IDs:
+
+ - 'text_entry_box.vertical_scroll_bar.#top_button'
+ - 'text_entry_box.vertical_scroll_bar.#bottom_button'
+ - 'text_entry_box.vertical_scroll_bar.#sliding_button'
+
+There is more information on theming the vertical scroll bar at :ref:`theme-vertical-scroll-bar`.
+
+Example
+-------
+
+Here is an example of a text entry box block in a JSON theme file, using the parameters described above.
+
+.. code-block:: json
+   :caption: text_entry_box.json
+   :linenos:
+
+    {
+        "text_entry_box":
+        {
+            "colours":
+            {
+                "dark_bg":"#21282D",
+                "normal_border": "#999999",
+                "link_text": "#FF0000",
+                "link_hover": "#FFFF00",
+                "link_selected": "#FFFFFF"
+            },
+
+            "misc":
+            {
+                "border_width": "1",
+                "padding": "10,10",
+                "link_normal_underline": "0",
+                "link_hover_underline": "1",
+                "line_spacing": "1.0"
+            }
+        },
+        "text_entry_box.vertical_scroll_bar":
+        {
+            "colours":
+            {
+               "dark_bg": "#505068"
+            }
+        },
+        "text_entry_box.vertical_scroll_bar.#sliding_button":
+        {
+            "misc":
+            {
+               "border_width": "1"
+            }
+        }
+    }

pygame_gui/data/default_theme.json

@@ -184,6 +184,24 @@
             "shadow_width": "0"
         }
     },
+    "text_entry_box":
+    {
+        "prototype": "#default_shape_style",
+        "misc":
+        {
+            "padding": "5,5",
+            "text_horiz_alignment_padding": "0",
+            "text_vert_alignment_padding": "0"
+        }
+    },
+    "text_entry_box.vertical_scroll_bar":
+    {
+        "misc":
+        {
+            "border_width": "1",
+            "shadow_width": "0"
+        }
+    },
     "text_entry_line":
     {
         "prototype": "#default_shape_style",

pygame_gui/elements/ui_text_box.py

@@ -67,12 +67,12 @@ class UITextBox(UIElement, IUITextOwnerInterface):
                     it will try to use the first UIManager that was created by your application.
     :param wrap_to_height: False by default, if set to True the box will increase in height to
                            match the text within.
-    :param layer_starting_height: Sets the height, above it's container, to start placing the text
+    :param layer_starting_height: Sets the height, above its container, to start placing the text
                                   box at.
     :param container: The container that this element is within. If not provided or set to None
                       will be the root window's container.
     :param parent_element: The element this element 'belongs to' in the theming hierarchy.
-    :param object_id: A custom defined ID for fine tuning of theming.
+    :param object_id: A custom defined ID for fine-tuning of theming.
     :param anchors: A dictionary describing what this element's relative_rect is relative to.
     :param visible: Whether the element is visible by default. Warning - container visibility
                     may override this.

pygame_gui/elements/ui_text_entry_box.py

@@ -16,6 +16,22 @@
 
 
 class UITextEntryBox(UITextBox):
+    """
+    Inherits from UITextBox but allows you to enter text with the keyboard, much like UITextEntryLine.
+
+    :param relative_rect: The 'visible area' rectangle, positioned relative to its container.
+    :param initial_text: The text that starts in the text box.
+    :param manager: The UIManager that manages this element. If not provided or set to None,
+                    it will try to use the first UIManager that was created by your application.
+    :param container: The container that this element is within. If not provided or set to None
+                      will be the root window's container.
+    :param parent_element: The element this element 'belongs to' in the theming hierarchy.
+    :param object_id: A custom defined ID for fine-tuning of theming.
+    :param anchors: A dictionary describing what this element's relative_rect is relative to.
+    :param visible: Whether the element is visible by default. Warning - container visibility
+                    may override this.
+    """
+
     def __init__(self,
                  relative_rect: Union[Rect, Tuple[int, int, int, int]],
                  initial_text: str = "",
@@ -25,6 +41,7 @@ def __init__(self,
                  object_id: Optional[Union[ObjectID, str]] = None,
                  anchors: Optional[Dict[str, Union[str, UIElement]]] = None,
                  visible: int = 1):
+
         super().__init__(initial_text,
                          relative_rect,
                          manager=manager,
@@ -37,6 +54,11 @@ def __init__(self,
                          plain_text_display_only=True,
                          should_html_unescape_input_text=True)
 
+        self._create_valid_ids(container=container,
+                               parent_element=parent_element,
+                               object_id=object_id,
+                               element_id='text_entry_box')
+
         # input timings - I expect nobody really wants to mess with these that much
         # ideally we could populate from the os settings but that sounds like a headache
         self.key_repeat = 0.5