From 33f5f9f81fc15dcdb76662298e318b90f624b699 Mon Sep 17 00:00:00 2001 From: Dan Lawrence Date: Sat, 31 Dec 2022 19:06:33 +0000 Subject: [PATCH] Add basic documentation for text entry box --- docs/source/theme_guide.rst | 1 + .../theme_reference/theme_text_entry_box.rst | 110 ++++++++++++++++++ pygame_gui/data/default_theme.json | 18 +++ pygame_gui/elements/ui_text_box.py | 4 +- pygame_gui/elements/ui_text_entry_box.py | 22 ++++ 5 files changed, 153 insertions(+), 2 deletions(-) create mode 100644 docs/source/theme_reference/theme_text_entry_box.rst diff --git a/docs/source/theme_guide.rst b/docs/source/theme_guide.rst index 750d2486..4d33645a 100644 --- a/docs/source/theme_guide.rst +++ b/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 diff --git a/docs/source/theme_reference/theme_text_entry_box.rst b/docs/source/theme_reference/theme_text_entry_box.rst new file mode 100644 index 00000000..ee0d78c7 --- /dev/null +++ b/docs/source/theme_reference/theme_text_entry_box.rst @@ -0,0 +1,110 @@ +.. _theme-text-box: + +UITextEntryBox Theming Parameters +=============================== + +.. raw:: html + + + +The :class:`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 ` 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 ` 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 ` 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" + } + } + } \ No newline at end of file diff --git a/pygame_gui/data/default_theme.json b/pygame_gui/data/default_theme.json index a184b1c5..504447c1 100644 --- a/pygame_gui/data/default_theme.json +++ b/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", diff --git a/pygame_gui/elements/ui_text_box.py b/pygame_gui/elements/ui_text_box.py index f0558729..e634c4d8 100644 --- a/pygame_gui/elements/ui_text_box.py +++ b/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. diff --git a/pygame_gui/elements/ui_text_entry_box.py b/pygame_gui/elements/ui_text_entry_box.py index 5471a995..3db473f0 100644 --- a/pygame_gui/elements/ui_text_entry_box.py +++ b/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