xSGE GUI Toolkit
****************


Contents
^^^^^^^^

* xSGE GUI Toolkit

  * xsge_gui Classes

    * xsge_gui.Handler

      * xsge_gui.Handler Methods

    * xsge_gui.Window

      * xsge_gui.Window Methods

      * xsge_gui.Window Event Methods

    * xsge_gui.Dialog

      * xsge_gui.Dialog Methods

    * xsge_gui.MenuWindow

      * xsge_gui.MenuWindow Methods

      * xsge_gui.MenuWindow Event Methods

    * xsge_gui.MenuDialog

    * xsge_gui.MessageDialog

    * xsge_gui.TextEntryDialog

    * xsge_gui.Widget

      * xsge_gui.Widget Methods

      * xsge_gui.Widget Event Methods

    * xsge_gui.DecorativeWidget

    * xsge_gui.Label

    * xsge_gui.ProgressiveLabel

      * xsge_gui.ProgressiveLabel Event Methods

    * xsge_gui.Button

      * xsge_gui.Button Event Methods

    * xsge_gui.CheckBox

      * xsge_gui.CheckBox Event Methods

    * xsge_gui.RadioButton

      * xsge_gui.RadioButton Event Methods

    * xsge_gui.ProgressBar

    * xsge_gui.TextBox

      * xsge_gui.TextBox Event Methods

    * xsge_gui.MenuItem

  * xsge_gui Functions

xSGE is a collection of higher-level extensions for the SGE which
enhance the core functionality in an implementation-independent way.
Like the SGE itself, they are distribted under the terms of the GNU
Lesser General Public License.

This extension provides a simple toolkit for adding GUIs to a SGE game
as well as support for modal dialog boxes.

To use this extension, you must call "xsge_gui.init()" sometime
between the creation of the "sge.dsp.Game" object and the start of the
game.

xsge_gui.window_background_color
xsge_gui.keyboard_focused_box_color
xsge_gui.text_color
xsge_gui.button_color
xsge_gui.button_pressed_color
xsge_gui.button_selected_color
xsge_gui.button_text_color
xsge_gui.textbox_color
xsge_gui.textbox_text_color
xsge_gui.textbox_text_selected_color
xsge_gui.textbox_highlight_color
xsge_gui.title_text_color

   The colors used by this module.  They can be safely changed, but be
   sure to call "redraw()" on all windows and widgets that would be
   affected; some changes might not become visible until you do.

xsge_gui.default_font
xsge_gui.button_font
xsge_gui.textbox_font
xsge_gui.title_font

   The fonts used by this module.  They can be safely changed, but be
   sure to call "redraw()" on all windows and widgets that would be
   affected; some changes might not become visible until you do.

xsge_gui.button_left_sprite
xsge_gui.button_right_sprite
xsge_gui.button_bottom_sprite
xsge_gui.button_bottomleft_sprite
xsge_gui.button_bottomright_sprite
xsge_gui.button_top_sprite
xsge_gui.button_topleft_sprite
xsge_gui.button_topright_sprite
xsge_gui.button_pressed_left_sprite
xsge_gui.button_pressed_right_sprite
xsge_gui.button_pressed_bottom_sprite
xsge_gui.button_pressed_bottomleft_sprite
xsge_gui.button_pressed_bottomright_sprite
xsge_gui.button_pressed_top_sprite
xsge_gui.button_pressed_topleft_sprite
xsge_gui.button_pressed_topright_sprite
xsge_gui.button_selected_left_sprite
xsge_gui.button_selected_right_sprite
xsge_gui.button_selected_bottom_sprite
xsge_gui.button_selected_bottomleft_sprite
xsge_gui.button_selected_bottomright_sprite
xsge_gui.button_selected_top_sprite
xsge_gui.button_selected_topleft_sprite
xsge_gui.button_selected_topright_sprite
xsge_gui.checkbox_off_sprite
xsge_gui.checkbox_on_sprite
xsge_gui.progressbar_sprite
xsge_gui.progressbar_left_sprite
xsge_gui.progressbar_right_sprite
xsge_gui.progressbar_container_sprite
xsge_gui.progressbar_container_left_sprite
xsge_gui.progressbar_container_right_sprite
xsge_gui.radiobutton_off_sprite
xsge_gui.radiobutton_on_sprite
xsge_gui.textbox_left_sprite
xsge_gui.textbox_right_sprite
xsge_gui.textbox_bottom_sprite
xsge_gui.textbox_bottomleft_sprite
xsge_gui.textbox_bottomright_sprite
xsge_gui.textbox_top_sprite
xsge_gui.textbox_topleft_sprite
xsge_gui.textbox_topright_sprite
xsge_gui.window_border_left_sprite
xsge_gui.window_border_right_sprite
xsge_gui.window_border_bottom_sprite
xsge_gui.window_border_bottomleft_sprite
xsge_gui.window_border_bottomright_sprite
xsge_gui.window_border_top_sprite
xsge_gui.window_border_topleft_sprite
xsge_gui.window_border_topright_sprite

   The sprites used by this module.  They can be safely changed, but
   be sure to call "redraw()" on all windows and widgets that would be
   affected; some changes might not become visible until you do.

   Note:

     Sprites which represent the same thing in a different form, such
     as the "selected" variants of button sprites, must be the same
     size as the regular variants.  Using different inconsistent sizes
     may lead to unexpected results.

xsge_gui.next_window_keys

   A list of keys which, when pressed, will give keyboard focus to the
   next available window.

   Default value: "[]"

xsge_gui.previous_window_keys

   A list of keys which, when pressed, will give keyboard focus to the
   previous available window.

   Default value: "[]"

xsge_gui.next_widget_keys

   A list of keys which, when pressed, will give keyboard focus to the
   next available widget on the window which has keyboard focus.

   Default value: "["tab"]"

xsge_gui.previous_widget_keys

   A list of keys which, when pressed, will give keyboard focus to the
   previous available widget on the window which has keyboard focus.

   Default value: "[]"

xsge_gui.left_keys

   A list of keys to treat as left arrows.

   Default value: "["left"]"

xsge_gui.right_keys

   A list of keys to treat as right arrows.

   Default value: "["right"]"

xsge_gui.up_keys

   A list of keys to treat as up arrows.

   Default value: "["up"]"

xsge_gui.down_keys

   A list of keys to treat as down arrows.

   Default value: "["down"]"

xsge_gui.enter_keys

   A list of keys to treat as Enter keys.

   Default value: "["enter", "kp_enter"]"

xsge_gui.escape_keys

   A list of keys to treat as Escape keys.

   Default value: "["escape"]"

xsge_gui.next_window_joystick_events

   A list of tuples indicating joystick events which will give
   keyboard focus to the next available window.

   The tuples should contain, in order, the following values:

   1. The number of the joystick, where "0" is the first joystick.

   2. The type of event.  See the documentation for
      "sge.input.JoystickEvent" for more information.

   3. The number of the joystick control, where "0" is the first
      control of its type on the joystick.

   Default value: "[]"

xsge_gui.previous_window_joystick_events

   A list of tuples indicating joystick events which will give
   keyboard focus to the previous available window.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[]"

xsge_gui.next_widget_joystick_events

   A list of tuples indicating joystick events which will give
   keyboard focus to the next available widget on the window which has
   keyboard focus.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[(0, "button", 8)]"

xsge_gui.previous_widget_joystick_events

   A list of tuples indicating joystick events which will give
   keyboard focus to the previous available widget on the window which
   has keyboard focus.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[]"

xsge_gui.left_joystick_events

   A list of tuples indicating joystick events to treat as left
   arrows.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[(0, "axis-", 0), (0, "hat_left", 0)]"

xsge_gui.right_joystick_events

   A list of tuples indicating joystick events to treat as right
   arrows.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[(0, "axis+", 0), (0, "hat_right", 0)]"

xsge_gui.up_joystick_events

   A list of tuples indicating joystick events to treat as up arrows.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[(0, "axis-", 1), (0, "hat_up", 0)]"

xsge_gui.down_joystick_events

   A list of tuples indicating joystick events to treat as down
   arrows.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[(0, "axis+", 1), (0, "hat_down", 0)]"

xsge_gui.enter_joystick_events

   A list of tuples indicating joystick events to treat as Enter keys.

   See the documentation for "next_window_joystick_events" for more
   information.

   Default value: "[(0, "button", 9)]"

xsge_gui.escape_joystick_events

   A list of tuples indicating joystick events to treat as Escape
   keys.

   Default value: "[]"

xsge_gui.joystick_threshold

   The amount of tilt on a joystick that should be considered
   "triggered" for the purpose of navigating menus.


xsge_gui Classes
================


xsge_gui.Handler
----------------

class xsge_gui.Handler

   An object of this class needs to exist in any room where windows
   are to be used.  It feeds SGE events to the windows so they can
   react to user input.  It also refreshes all windows every frame.

   windows

      A list of all windows that are currently handled by this
      handler.

      You don't need to modify this list manually.  Instead, use
      "xsge_gui.Window.show()" and "xsge_gui.Window.hide()" to add and
      remove windows from this list, respectively.

   keyboard_focused_window

      The window that currently has keyboard focus, or "None" if no
      window has focus.


xsge_gui.Handler Methods
~~~~~~~~~~~~~~~~~~~~~~~~

Handler.get_mouse_focused_window()

   Return the window that currently has mouse focus.  The window with
   mouse focus is the one which is closest to the front that is
   touching the mouse cursor.

   Return "None" if no window has focus.


xsge_gui.Window
---------------

class xsge_gui.Window(parent, x, y, width, height, title='', background_color=None, border=True)

   Window objects are used to contain widgets.  They can be moved
   around the game window by the user.

   parent

      A weak reference to this window's parent handler object, which
      is used to display it when it is supposed to be visible.

      If a strong reference is assigned to this attribute, it will
      automatically be changed to a weak reference.

   x

      The horizontal position of the window relative to the game
      window.

   y

      The vertical position of the window relative to the game window.

   width

      The width of the window.

   height

      The height of the window.

   title

      The text that shows up in the title bar of the window.

   background_color

      The color of this window's background.  If set to "None", it
      becomes the same value as "xsge_gui.window_background_color".

   border

      Whether or not the window has a border.  If this is "False", the
      window cannot be moved or resized by the user, and "title" will
      not be displayed.

   widgets

      A list of this window's widgets.

   keyboard_focused_widget

      The widget which currently has keyboard focus within this
      window, or "None" if no widget has keyboard focus within this
      window.

   sprite

      The sprite this window currently displays as itself.


xsge_gui.Window Methods
~~~~~~~~~~~~~~~~~~~~~~~

Window.show()

   Add this window to its parent handler.

Window.hide()

   Remove this window from its parent handler.

Window.move_to_front()

   Move this window in front of all other windows.

Window.move_to_back()

   Move this window behind all other windows.

Window.destroy()

   An alias for "xsge_gui.Window.hide()".

Window.redraw()

   Re-draw this window's sprite.

   Call this method if you change any variables that should affect
   this window's appearance. For performance reasons, the changes
   won't show up in an existing window until this method is called.

Window.refresh()

   Project this window onto the game window.

   This method must be called every frame for the window to be
   visible.

Window.get_mouse_on_titlebar()

   Return whether or not the mouse is on the title bar.

Window.get_mouse_focused_widget()

   Return the widget in this window with mouse focus.  The widget with
   mouse focus is the one which is closest to the front that is
   touching the mouse cursor.

   Return "None" if no widget has focus.


xsge_gui.Window Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Window.event_step(time_passed, delta_mult)

   Called once every frame, before refreshing.  See the documentation
   for "sge.dsp.Game.event_step()" for more information.

Window.event_change_keyboard_focus()

   Called when "keyboard_focused_widget" changes as a result of a key
   or joystick event being pressed.

Window.event_key_press(key, char)

   Called when a key is pressed while this window has keyboard focus.
   See the documentation for "sge.input.KeyPress" for more
   information.

Window.event_key_release(key)

   Called when a key is released while this window has keyboard focus.
   See the documentation for "sge.input.KeyRelease" for more
   information.

Window.event_mouse_button_press(button)

   Called when a mouse button is pressed while this window has mouse
   focus.  See the documentation for "sge.input.MouseButtonPress" for
   more information.

Window.event_mouse_button_release(button)

   Called when a mouse button is released while this window has mouse
   focus.  See the documentation for "sge.input.MouseButtonRelease"
   for more information.

Window.event_joystick_axis_move(js_name, js_id, axis, value)

   Called when a joystick axis is moved while this window has keyboard
   focus.  See the documentation for "sge.input.JoystickAxisMove" for
   more information.

Window.event_joystick_hat_move(js_name, js_id, hat, x, y)

   Called when a joystick hat is moved while this window has keyboard
   focus.  See the documentation for "sge.input.JoystickHatMove" for
   more information.

Window.event_joystick_trackball_move(js_name, js_id, ball, x, y)

   Called when a joystick trackball is moved while this window has
   keyboard focus.  See the documentation for
   "sge.input.JoystickTrackballMove" for more information.

Window.event_joystick_button_press(js_name, js_id, button)

   Called when a joystick button is pressed while this window has
   keyboard focus.  See the documentation for
   "sge.input.JoystickButtonPress" for more information.

Window.event_joystick_button_release(js_name, js_id, button)

   Called when a joystick button is released while this window has
   keyboard focus.  See the documentation for
   "sge.input.JoystickButtonRelease" for more information.

Window.event_joystick(js_name, js_id, input_type, input_id, value)

   Called when a joystick event occurs while this window has keyboard
   focus.  See the documentation for "sge.inputJoystickEvent" for more
   information.

Window.event_press_left()

   Called when a key in "left_keys" or a joystick event in
   "left_joystick_events" is pressed while this window has keyboard
   focus.

Window.event_press_right()

   Called when a key in "right_keys" or a joystick event in
   "right_joystick_events" is pressed while this window has keyboard
   focus.

Window.event_press_up()

   Called when a key in "up_keys" or a joystick event in
   "up_joystick_events" is pressed while this window has keyboard
   focus.

Window.event_press_down()

   Called when a key in "down_keys" or a joystick event in
   "down_joystick_events" is pressed while this window has keyboard
   focus.

Window.event_press_enter()

   Called when a key in "enter_keys" or a joystick event in
   "enter_joystick_events" is pressed while this window has keyboard
   focus.

Window.event_press_escape()

   Called when a key in "escape_keys" or a joystick event in
   "enter_joystick_events" is pressed while this window has keyboard
   focus.

Window.event_release_left()

   Called when a key in "left_keys" or a joystick event in
   "left_joystick_events" is released while this window has keyboard
   focus.

Window.event_release_right()

   Called when a key in "right_keys" or a joystick event in
   "right_joystick_events" is released while this window has keyboard
   focus.

Window.event_release_up()

   Called when a key in "up_keys" or a joystick event in
   "up_joystick_events" is released while this window has keyboard
   focus.

Window.event_release_down()

   Called when a key in "down_keys" or a joystick event in
   "down_joystick_events" is released while this window has keyboard
   focus.

Window.event_release_enter()

   Called when a key in "enter_keys" or a joystick event in
   "enter_joystick_events" is released while this window has keyboard
   focus.

Window.event_release_escape()

   Called when a key in "escape_keys" or a joystick event in
   "enter_joystick_events" is released while this window has keyboard
   focus.

Window.event_titlebar_mouse_button_press(button)

   Called when a mouse button is pressed on top of this window's title
   bar (top border).  See the documentation for
   "sge.input.MouseButtonPress" for more information.

Window.event_titlebar_mouse_button_release(button)

   Called when a mouse button is released on top of this window's
   title bar (top border).  See the documentation for
   "sge.input.MouseButtonRelease" for more information.

Window.event_global_key_press(key, char)

   Called when a key is pressed, regardless of which window has
   keyboard focus.  See the documentation for "sge.input.KeyPress" for
   more information.

Window.event_global_key_release(key)

   Called when a key is released, regardless of which window has
   keyboard focus.  See the documentation for "sge.input.KeyRelease"
   for more information.

Window.event_global_mouse_button_press(button)

   Called when a mouse button is pressed, regardless of which window
   has mouse focus.  See the documentation for
   "sge.input.MouseButtonPress" for more information.

Window.event_global_mouse_button_release(button)

   Called when a mouse button is released, regardless of which window
   has mouse focus.  See the documentation for
   "sge.input.MouseButtonRelease" for more information.

Window.event_global_joystick_axis_move(js_name, js_id, axis, value)

   Called when a joystick axis is moved, regardless of which window
   has keyboard focus.  See the documentation for
   "sge.input.JoystickAxisMove" for more information.

Window.event_global_joystick_hat_move(js_name, js_id, hat, x, y)

   Called when a joystick hat is moved, regardless of which window has
   keyboard focus.  See the documentation for
   "sge.input.JoystickHatMove" for more information.

Window.event_global_joystick_trackball_move(js_name, js_id, ball, x, y)

   Called when a joystick trackball is moved, regardless of which
   window has keyboard focus.  See the documentation for
   "sge.input.JoystickTrackballMove" for more information.

Window.event_global_joystick_button_press(js_name, js_id, button)

   Called when a joystick button is pressed, regardless of which
   window has keyboard focus.  See the documentation for
   "sge.input.JoystickButtonPress" for more information.

Window.event_global_joystick_button_release(js_name, js_id, button)

   Called when a joystick button is released, regardless of which
   window has keyboard focus.  See the documentation for
   "sge.input.JoystickButtonRelease" for more information.

Window.event_global_joystick(js_name, js_id, input_type, input_id, value)

   Called when a joystick event occurs, regardless of which window has
   keyboard focus.  See the documentation for "sge.inputJoystickEvent"
   for more information.


xsge_gui.Dialog
---------------

class xsge_gui.Dialog(parent, x, y, width, height, title='', background_color=None, border=True)

   Dialog class.

   Dialogs are windows with their own loops, also called modal
   windows. They are used for tasks that must be completed before the
   main program continues, such as pop-up messages.

   See the documentation for "xsge_gui.Window" for more information.


xsge_gui.Dialog Methods
~~~~~~~~~~~~~~~~~~~~~~~

In addition to methods inherited from "xsge_gui.Window", the following
methods are also available:

Dialog.show()

   Show this dialog and start its loop.

   Like "xsge_gui.Window.show()", this method adds the dialog to its
   parent.  It then starts this dialog's loop.  Call
   "xsge_gui.Dialog.hide()" on this dialog to end the loop.

   The loop suppresses all events, but allows the Quit event to
   propagate.


xsge_gui.MenuWindow
-------------------

class xsge_gui.MenuWindow(parent, x, y, width, height, title='', background_color=sge.gfx.Color('#00000000'), border=False)

   Meant to  be used with "xsge_gui.MenuItem" widgets to create
   keyboard-navigated menus.  Has no border by default.  If one of the
   keys in "enter_keys" or one of the joystick events in
   "enter_joystick_events" is pressed, "choice" is set to the index
   within "widgets" of the widget which currently has keyboard focus,
   the window is closed, and "event_choose()" is called.  If one of
   the keys in "escape_keys" or one of the joystick events in
   "escape_joystick_events" is pressed, the window is closed and
   "event_choose()" is called.

   choice

      The menu item chosen.  If no menu item has been chosen, it is
      set to "None".

   See the documentation for "xsge_gui.Window" for more information.


xsge_gui.MenuWindow Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the methods inherited from "xsge_gui.Window", the
following methods are also available:

classmethod MenuWindow.from_text(parent, x, y, items, font_normal=None, color_normal=None, font_selected=None, color_selected=None, background_color=sge.gfx.Color('#00000000'), height=None, margin=0, halign='left', valign='top', outline_normal=None, outline_selected=None, outline_thickness_normal=0, outline_thickness_selected=0, selection_prefix='', selection_suffix='')

   Return a menu created automatically from a list of strings.

   Arguments:

   * "x" -- The horizontal location of the window within the room.
     Affected by "halign".

   * "y" -- The vertical location of the window within the room.
     Affected by "valign".

   * "items" -- A list of strings to use as the menu's items.

   * "font_normal" -- The default font to use.

   * "color_normal" -- The default color to use.

   * "font_selected" -- The font to use for the currently selected
     item.  If set to "None", the default font will be used.

   * "color_selected" -- The color to use for the currently selected
     item.  If set to "None", the default color will be used.

   * "height" -- The height of the menu.  If set to "None", it will be
     the sum of the items' height.

   * "margin" -- The size of the margin around the menu.

   * "halign" -- The horizontal alignment of the menu.  See the
     documentation for "sge.gfx.Sprite.draw_text()" for more
     information.

   * "valign" -- The vertical alignment of the menu.  See the
     documentation for "sge.gfx.Sprite.draw_text()" for more
     information.

   * "outline_normal" -- The default outline color to use.  See the
     documentation for "sge.gfx.Sprite.draw_text()" for more
     information.

   * "outline_selected" -- The outline color to use for the currently
     selected item.  See the documentation for
     "sge.gfx.Sprite.draw_text()" for more information.

   * "outline_thickness_normal" -- The default outline thickness to
     use. See the documentation for "sge.gfx.Sprite.draw_text()" for
     more information.

   * "outline_thickness_selected" -- The outline thickness to use for
     the currently selected item. See the documentation for
     "sge.gfx.Sprite.draw_text()" for more information.

   * "selection_prefix" -- A prefix to prepend to the text of the
     current selection.  Useful for colorblind accessibility.

   * "selection_suffix" -- A suffix to append to the text of the
     current selection.  Useful for colorblind accessibility.


xsge_gui.MenuWindow Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the event methods inherited from "xsge_gui.Window", the
following event methods are also available:

MenuWindow.event_choose()

   Called when a menu item is chosen.


xsge_gui.MenuDialog
-------------------

class xsge_gui.MenuDialog(parent, x, y, width, height, title='', background_color=sge.gfx.Color('#00000000'), border=False)

   Inherits both "MenuWindow" and "Dialog".

   See the documentation for "xsge_gui.Dialog" for more information.


xsge_gui.MessageDialog
----------------------

class xsge_gui.MessageDialog(parent, message='', title='Message', buttons=('Ok'), default=- 1, width=320, height=None)

   This dialog shows a message box and accepts button input.  All
   buttons cause the dialog to close and set "choice" to the button
   pressed.

   choice

      The button clicked.  If a button hasn't been clicked (i.e. the
      dialog hasn't yet been closed or was closed by clicking on the
      close button), it is set to "None".

   See the documentation for "xsge_gui.Dialog" for more information.


xsge_gui.TextEntryDialog
------------------------

class xsge_gui.TextEntryDialog(parent, message='', title='Text Entry', text='', width=320, height=None)

   This dialog shows a message and has the user enter some text.  Two
   buttons are shown: a "Cancel" button that closes the dialog, and an
   "Ok" button that sets "text" to the text entered and then closes
   the dialog.

   text

      The text entered after the "Ok" button is clicked.  If the "Ok"
      button hasn't been clicked, this is "None".

   See the documentation for "xsge_gui.Dialog" for more information.


xsge_gui.Widget
---------------

class xsge_gui.Widget(parent, x, y, z, sprite=None, index=None)

   Widget objects are things like controls and decorations that exist
   on windows.

   parent

      A weak reference to this widget's parent window.

      If a strong reference is assigned to this attribute, it will
      automatically be changed to a weak reference.

   x

      The horizontal position of the widget relative to its parent
      window.

   y

      The vertical position of the widget relative to its parent
      window.

   z

      The Z-axis position of the widget.  Widgets with a higher Z-axis
      value are in front of widgets with a lower Z-axis value.  This
      value is not connected in any way to Z-axis values in the SGE.

   sprite

      The sprite this widget displays as itself.

   index

      Indicates the "position" this widget is in for the purposes of
      tab-focusing.  Smaller indexes are first on the window's list of
      widgets.  Set to "None" to use "z" for this purpose. Widgets
      with smaller indexes are inserted earlier in the parent window's
      "widgets" list, and this positioning is what actually determines
      the ordering of tab-focusing.

      Note:

        This attribute does not *precisely* control the index of the
        widget within the parent widget's "widgets" list. It only
        controls where the widget is in the list relative to other
        widgets.

   tab_focus

      Class attribute indicating whether or not the widget should be
      considered for focusing when the Tab key is pressed.

      Default value: "True"


xsge_gui.Widget Methods
~~~~~~~~~~~~~~~~~~~~~~~

Widget.destroy()

   Destroy this widget.

Widget.redraw()

   Re-draw this widget's sprite.

   Call this method if you change any variables that should affect
   this widget's appearance.  This method automatically makes any
   changes necessary to "self.sprite".

Widget.refresh()

   Project this widget onto the game window.

   This method must be called every frame for the widget to be
   visible.


xsge_gui.Widget Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Widget.event_step(time_passed, delta_mult)

   Called once every frame, before refreshing.  See the documentation
   for "sge.dsp.Game.event_step()" for more information.

Widget.event_key_press(key, char)

   Called when a key is pressed while this widget has keyboard focus.
   See the documentation for "sge.input.KeyPress" for more
   information.

Widget.event_key_release(key)

   Called when a key is released while this widget has keyboard focus.
   See the documentation for "sge.input.KeyRelease" for more
   information.

Widget.event_mouse_button_press(button)

   Called when a mouse button is pressed while this widget has mouse
   focus.  See the documentation for "sge.input.MouseButtonPress" for
   more information.

Widget.event_mouse_button_release(button)

   Called when a mouse button is released while this widget has mouse
   focus.  See the documentation for "sge.input.MouseButtonRelease"
   for more information.

Widget.event_joystick_axis_move(js_name, js_id, axis, value)

   Called when a joystick axis is moved while this widget has keyboard
   focus.  See the documentation for "sge.input.JoystickAxisMove" for
   more information.

Widget.event_joystick_hat_move(js_name, js_id, hat, x, y)

   Called when a joystick hat is moved while this widget has keyboard
   focus.  See the documentation for "sge.input.JoystickHatMove" for
   more information.

Widget.event_joystick_trackball_move(js_name, js_id, ball, x, y)

   Called when a joystick trackball is moved while this widget has
   keyboard focus.  See the documentation for
   "sge.input.JoystickTrackballMove" for more information.

Widget.event_joystick_button_press(js_name, js_id, button)

   Called when a joystick button is pressed while this widget has
   keyboard focus.  See the documentation for
   "sge.input.JoystickButtonPress" for more information.

Widget.event_joystick_button_release(js_name, js_id, button)

   Called when a joystick button is released while this widget has
   keyboard focus.  See the documentation for
   "sge.input.JoystickButtonRelease" for more information.

Widget.event_joystick(js_name, js_id, input_type, input_id, value)

   Called when a joystick event occurs while this widget has keyboard
   focus.  See the documentation for "sge.input.JoystickEvent" for
   more information.

Widget.event_press_left()

   Called when a key in "left_keys" or a joystick event in
   "left_joystick_events" is pressed while this widget has keyboard
   focus.

Widget.event_press_right()

   Called when a key in "right_keys" or a joystick event in
   "right_joystick_events" is pressed while this widget has keyboard
   focus.

Widget.event_press_up()

   Called when a key in "up_keys" or a joystick event in
   "up_joystick_events" is pressed while this widget has keyboard
   focus.

Widget.event_press_down()

   Called when a key in "down_keys" or a joystick event in
   "down_joystick_events" is pressed while this widget has keyboard
   focus.

Widget.event_press_enter()

   Called when a key in "enter_keys" or a joystick event in
   "enter_joystick_events" is pressed while this widget has keyboard
   focus.

Widget.event_press_escape()

   Called when a key in "escape_keys" or a joystick event in
   "enter_joystick_events" is pressed while this widget has keyboard
   focus.

Widget.event_release_left()

   Called when a key in "left_keys" or a joystick event in
   "left_joystick_events" is released while this widget has keyboard
   focus.

Widget.event_release_right()

   Called when a key in "right_keys" or a joystick event in
   "right_joystick_events" is released while this widget has keyboard
   focus.

Widget.event_release_up()

   Called when a key in "up_keys" or a joystick event in
   "up_joystick_events" is released while this widget has keyboard
   focus.

Widget.event_release_down()

   Called when a key in "down_keys" or a joystick event in
   "down_joystick_events" is released while this widget has keyboard
   focus.

Widget.event_release_enter()

   Called when a key in "enter_keys" or a joystick event in
   "enter_joystick_events" is released while this widget has keyboard
   focus.

Widget.event_release_escape()

   Called when a key in "escape_keys" or a joystick event in
   "enter_joystick_events" is released while this widget has keyboard
   focus.

Widget.event_global_key_press(key, char)

   Called when a key is pressed, regardless of which widget has
   keyboard focus.  See the documentation for "sge.input.KeyPress" for
   more information.

Widget.event_global_key_release(key)

   Called when a key is released, regardless of which widget has
   keyboard focus.  See the documentation for "sge.input.KeyRelease"
   for more information.

Widget.event_global_mouse_button_press(button)

   Called when a mouse button is pressed, regardless of which widget
   has mouse focus.  See the documentation for
   "sge.input.MouseButtonPress" for more information.

Widget.event_global_mouse_button_release(button)

   Called when a mouse button is released, regardless of which widget
   has mouse focus.  See the documentation for
   "sge.input.MouseButtonRelease" for more information.

Widget.event_global_joystick_axis_move(js_name, js_id, axis, value)

   Called when a joystick axis is moved, regardless of which widget
   has keyboard focus.  See the documentation for
   "sge.input.JoystickAxisMove" for more information.

Widget.event_global_joystick_hat_move(js_name, js_id, hat, x, y)

   Called when a joystick hat is moved, regardless of which widget has
   keyboard focus.  See the documentation for
   "sge.input.JoystickHatMove" for more information.

Widget.event_global_joystick_trackball_move(js_name, js_id, ball, x, y)

   Called when a joystick trackball is moved, regardless of which
   widget has keyboard focus.  See the documentation for
   "sge.input.JoystickTrackballMove" for more information.

Widget.event_global_joystick_button_press(js_name, js_id, button)

   Called when a joystick button is pressed, regardless of which
   widget has keyboard focus.  See the documentation for
   "sge.input.JoystickButtonPress" for more information.

Widget.event_global_joystick_button_release(js_name, js_id, button)

   Called when a joystick button is released, regardless of which
   widget has keyboard focus.  See the documentation for
   "sge.input.JoystickButtonRelease" for more information.


xsge_gui.DecorativeWidget
-------------------------

class xsge_gui.DecorativeWidget(parent, x, y, z, sprite=None, index=None)

   Identical to "Widget", except that "tab_focus" is "False" by
   default.


xsge_gui.Label
--------------

class xsge_gui.Label(parent, x, y, z, text, font=None, width=None, height=None, color=None, halign='left', valign='top')

   This widget simply displays some text.

   text

      The text this label should display.

   font

      The font this label's text should be rendered with.  If set to
      "None", the value of "xsge_gui.default_font" is used.

   width

      The width of the imaginary rectangle the text is drawn in.  See
      the documentation for "sge.gfx.Sprite.draw_text()" for more
      information.

   height

      The height of the imaginary rectangle the text is drawn in.  See
      the documentation for "sge.gfx.Sprite.draw_text()" for more
      information.

   halign

      The horizontal alignment of the text.  See the documentation for
      "sge.gfx.Sprite.draw_text()" for more information.

   valign

      The vertical alignment of the text.  See the documentation for
      "sge.gfx.Sprite.draw_text()" for more information.

   See the documentation for "xsge_gui.Widget" for more information.


xsge_gui.ProgressiveLabel
-------------------------

class xsge_gui.ProgressiveLabel(parent, x, y, z, full_text, font=None, width=None, height=None, color=None, halign='left', valign='top', rate=1000)

   This widget is a version of "xsge_gui.Label" which progressively
   builds "text" one character at a time, making it look like the text
   is being typed in real-time.

   full_text

      The value that "text" progressively becomes.

   rate

      The rate at which "text" is built in characters per minute.


xsge_gui.ProgressiveLabel Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the event methods inherited from "xsge_gui.Widget", the
following event methods are also available:

ProgressiveLabel.event_add_character()

   Called when a character is added to "text".


xsge_gui.Button
---------------

class xsge_gui.Button(parent, x, y, z, text, width=None, halign='center')

   This widget contains some text and can be clicked on by the user.

   text

      The text contained in the button.

   width

      The width of the button.  If set to "None", the width is chosen
      based on the width of the rendered text.

   halign

      The horizontal alignment of the text.  See the documentation for
      "sge.gfx.Sprite.draw_text()" for more information.

   See the documentation for "xsge_gui.Widget" for more information.


xsge_gui.Button Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the event methods inherited from "xsge_gui.Widget", the
following event methods are also available:

Button.event_press()

   Called when this button is clicked on, or when the Enter key is
   pressed while this button is selected.


xsge_gui.CheckBox
-----------------

class xsge_gui.CheckBox(parent, x, y, z, enabled=False)

   This widget can be toggled "on" or "off" by clicking on it.

   enabled

      Whether or not the checkbox is on.

   See the documentation for "xsge_gui.Widget" for more information.


xsge_gui.CheckBox Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the event methods inherited from "xsge_gui.Widget", the
following event methods are also available:

CheckBox.event_toggle()

   Called when the state of the checkbox is toggled by the user.


xsge_gui.RadioButton
--------------------

class xsge_gui.RadioButton(parent, x, y, z, enabled=False, group=None)

   This widget is mostly like "xsge_gui.CheckBox", but only one radio
   button in its group (determined by the "group" attribute) can be on
   at any given time (i.e. enabling one radio button on a window will
   disable all others on the same group in the same window).

   group

      Any value (typically a string) indicating the group of the radio
      button.  Only one radio button with a particular group value can
      be selected at once.

   See the documentation for "xsge_gui.CheckBox" for more information.


xsge_gui.RadioButton Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the event methods inherited from "xsge_gui.Widget", the
following event methods are also available:

RadioButton.event_toggle()

   Called when the state of the radiobutton is toggled, including when
   it is toggled off as a result of another radio button in the same
   group being toggled on.


xsge_gui.ProgressBar
--------------------

class xsge_gui.ProgressBar(parent, x, y, z, width=128, progress=0)

   This widget displays a bar which can be used to show progress (e.g.
   of some task being done).

   width

      The width of the progress bar.

   progress

      The progress indicated by the progress bar as a factor (i.e. "0"
      is no completion, "1" is full completion, and "0.5" is half
      completion).


xsge_gui.TextBox
----------------

class xsge_gui.TextBox(parent, x, y, z, width=32, text='', text_limit=1000)

   This widget provides a place for the user to enter text.

   width

      The width of the text box.

   text

      The text in the text box.

   text_limit

      The maximum number of characters allowed in the text box.

   See the documentation for "xsge_gui.Widget" for more information.


xsge_gui.TextBox Event Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the event methods inherited from "xsge_gui.Widget", the
following event methods are also available:

TextBox.event_change_text()

   Change text event.

   Called when the user changes the text in the textbox.


xsge_gui.MenuItem
-----------------

class xsge_gui.MenuItem(parent, x, y, z, sprite_normal=None, sprite_selected=None)

   This widget has two sprites: one for when it is selected, and one
   for when it is unselected.  Meant to be used with
   "xsge_gui.MenuWindow" or "xsge_gui.MenuDialog".

   sprite_normal

      The sprite to use as "sprite" when this widget is unselected.

   sprite_selected

      The sprite to use as "sprite" when this widget is selected.

   See the documentation for "xsge_gui.Widget" for more information.


xsge_gui Functions
==================

xsge_gui.init()

   Prepare this module for use.  This function in particular creates
   the sprites and fonts it uses for windows and widgets.  Because of
   this, it must not be called until after a "sge.dsp.Game" object has
   been created.

xsge_gui.show_message(parent=None, message='', title='Message', buttons=('Ok'), default=- 1, width=320, height=None)

   Show a message and return the button pressed.

   Arguments:

   * "parent" -- The parent handler of the "xsge_gui.MessageDialog"
     object created.  Set to "None" to create a new handler and then
     destroy it after the dialog is shown.

   * "message" -- The message shown to the user.

   * "title" -- The window title of the "xsge_gui.MessageDialog"
     object created.

   * "buttons" -- A list of strings to put inside the buttons, from
     left to right.

   * "default" -- The index of the default button selected by the
     keyboard (i.e. the default choice).

   * "width" -- The width of the "xsge_gui.MessageDialog" object
     created.

   * "height" -- The height of the "xsge_gui.MessageDialog" object
     created.  If set to "None", set the height automatically based on
     the space needed for the text.

   Value returned is the index of the button pressed, where "0" is the
   leftmost button, or "None" if no button was pressed (i.e. the close
   button on the window frame was pressed instead).

   See the documentation for "xsge_gui.MessageDialog" for more
   information.

xsge_gui.get_text_entry(parent=None, message='', title='Text Entry', text='', width=320, height=None)

   Return text entered by the user.

   Arguments:

   * "parent" -- The parent handler of the "xsge_gui.MessageDialog"
     object created.  Set to "None" to create a new handler and then
     destroy it after the dialog is shown.

   * "message" -- The message shown to the user.

   * "title" -- The window title of the "xsge_gui.TextEntryDialog"
     object created.

   * "text" -- The text in the text box by default.

   * "width" -- The width of the "xsge_gui.TextEntryDialog" object
     created.

   * "height" -- The height of the "xsge_gui.TextEntryDialog" object
     created.  If set to "None", set the height automatically based on
     the space needed for the text.

   Value returned is the text entered if the "Ok" button is pressed,
   or "None" otherwise.

   See the documentation for "xsge_gui.TextEntryDialog" for more
   information.

xsge_gui.get_menu_selection(x, y, items, parent=None, default=0, font_normal=None, color_normal=None, font_selected=None, color_selected=None, background_color=sge.gfx.Color('#00000000'), height=None, margin=0, halign='left', valign='top', outline_normal=None, outline_selected=None, outline_thickness_normal=0, outline_thickness_selected=0, selection_prefix='', selection_suffix='')

   Show a menu and return the index of the menu item selected.

   Arguments:

   * "parent" -- The parent handler of the "xsge_gui.TextMenuDialog"
     object created.  Set to "None" to create a new handler and then
     destroy it after the dialog is shown.

   * "default" -- The index of the item to select by default.

   See the documentation for "xsge_gui.MenuWindow.from_text" for more
   information.
