Getting Started¶

This tutorial is intended to get you up and running with Bgui quickly and easily. This tutorial assumes you already know how to use Python with the BGE. If you do not, take a look here.

import bgui
import bgui.bge_utils
import bge


class SimpleLayout(bgui.bge_utils.Layout):
    """A layout showcasing various Bgui features"""

    def __init__(self, sys, data):
        super().__init__(sys, data)

        # Add widgets here

def main(cont):
    own = cont.owner
    mouse = bge.logic.mouse

    if 'sys' not in own:
        # Create our system and show the mouse
        own['sys'] = bgui.bge_utils.System('../../themes/default')
        own['sys'].load_layout(SimpleLayout, None)
        mouse.visible = True
    else:
        own['sys'].run()

# Use a frame to store all of our widgets
self.frame = bgui.Frame(self, border=0)
self.frame.colors = [(0, 0, 0, 0) for i in range(4)]

# A Label widget
self.lbl = bgui.Label(self.frame, text='I sure wish someone would push that button...',
        pt_size=70, pos=[0, 0.7], options=bgui.BGUI_CENTERX)

# A FrameButton widget
self.btn = bgui.FrameButton(self.frame, text='Click Me!', size=[0.3, 0.1], pos=[0, 0.4],
        options=bgui.BGUI_CENTERX)

self.btn.on_click = self.button_click

def button_click(self, widget):
    self.lbl.text = 'Yippie! You clicked the button! ^_^'

bge_utils¶

class bgui.bge_utils.Layout(sys, data)¶

Bases: bgui.widget.Widget

A base layout class to be used with the BGESystem

Parameters:	sys – The BGUI system data – User data

update()¶

A function that is called by the system to update the widget (subclasses should override this)

class bgui.bge_utils.System(theme=None)¶

Bases: bgui.system.System

A system that is intended to be used with BGE games

Parameters:	theme – the path to a theme directory

load_layout(layout, data=None)¶

Load a layout and replace any previously loaded layout

Parameters:	layout – The layout to load (None to have no layouts loaded) data – User data to send to the layout’s constructor

add_overlay(overlay, data=None)¶

Add an overlay layout, which sits on top of the currently loaded layout

Parameters:	overlay – The layout to add as an overlay data – User data to send to the layout’s constructor

remove_overlay(overlay)¶

Remove an overlay layout by name

Parameters:	overlay – the class name of the overlay to remove (this is the same name as the layout used to add the overlay)

toggle_overlay(overlay, data=None)¶

Toggle an overlay (if the overlay is active, remove it, otherwise add it)

Parameters:	overlay – The class name of the layout to toggle data – User data to send to the layout’s constructor

run()¶

A high-level method to be run every frame

frame¶

class bgui.frame.Frame(parent, name=None, border=None, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', options=0)¶

Bases: bgui.widget.Widget

Frame for storing other widgets

Parameters:	parent – the widget’s parent name – the name of the widget border – the size of the border around the frame (0 for no border) aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

theme_section = 'Frame'¶

theme_options = {'Color2': (0, 0, 0, 0), 'Color4': (0, 0, 0, 0), 'BorderColor': (0, 0, 0, 1), 'BorderSize': 0, 'Color1': (0, 0, 0, 0), 'Color3': (0, 0, 0, 0)}¶

colors = None¶

The colors for the four corners of the frame.

border_color = None¶

The color of the border around the frame.

frame_button¶

class bgui.frame_button.FrameButton(parent, name=None, base_color=None, text='', font=None, pt_size=None, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', options=0)¶

Bases: bgui.widget.Widget

A clickable frame-based button.

Parameters:

parent – the widget’s parent name – the name of the widget base_color – the color of the button text – the text to display (this can be changed later via the text property) font – the font to use pt_size – the point size of the text to draw (defaults to 30 if None) aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

theme_section = 'FrameButton'¶

theme_options = {'BorderColor': (0, 0, 0, 1), 'Color': (0.4, 0.4, 0.4, 1), 'BorderSize': 1, 'LabelSubTheme': ''}¶

text¶

color¶

gl_utils¶

bgui.gl_utils.glGenTextures(n, textures=None)¶

bgui.gl_utils.glDeleteTextures(textures)¶

bgui.gl_utils.glGetIntegerv(pname)¶

image¶

This module defines the following constants:

Texture interpolation modes

• BGUI_NEAREST
• BGUI_LINEAR

class bgui.image.Image(parent, img, name=None, aspect=None, size=[1, 1], pos=[0, 0], texco=[(0, 0), (1, 0), (1, 1), (0, 1)], interp_mode=<class 'GL_LINEAR'>, sub_theme='', options=0)¶

Bases: bgui.widget.Widget

Widget for displaying images

Parameters:

parent – the widget’s parent name – the name of the widget img – the image to use for the widget aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position texco – the UV texture coordinates to use for the image interp_mode – texture interpolating mode for both maximizing and minifying the texture (defaults to BGUI_LINEAR) sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

texco = None¶

The UV texture coordinates to use for the image.

color = None¶

The color of the plane the texture is on.

interp_mode¶

The type of image filtering to be performed on the texture.

image_size¶

The size (in pixels) of the currently loaded image, or [0, 0] if an image is not loaded

update_image(img)¶

Changes the image texture

Parameters:	img – the path to the new image
Return type:	None

image_button¶

class bgui.image_button.ImageButton(parent, name=None, default_image=None, default2_image=None, hover_image=None, click_image=None, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', options=0)¶

Bases: bgui.widget.Widget

A clickable image-based button.

Parameters:

parent – the widget’s parent name – the name of the widget default_image – list containing image data for the default state (‘image’, xcoord, ycoord, xsize, ysize) default2_image – list containing image data for a second default state, which is used for toggling (‘image’, xcoord, ycoord, xsize, ysize) hover_image – list containing image data for the hover state (‘image’, xcoord, ycoord, xsize, ysize) click_image – list containing image data for the click state (‘image’, xcoord, ycoord, xsize, ysize) aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

theme_section = 'ImageButton'¶

theme_options = {'DefaultImage': (None, 0, 0, 1, 1), 'Default2Image': (None, 0, 0, 1, 1), 'ClickImage': (None, 0, 0, 1, 1), 'HoverImage': (None, 0, 0, 1, 1)}¶

key_defs¶

label¶

class bgui.label.Label(parent, name=None, text='', font=None, pt_size=None, color=None, outline_color=None, outline_size=None, outline_smoothing=None, pos=[0, 0], sub_theme='', options=0)¶

Bases: bgui.widget.Widget

Widget for displaying text

Parameters:

parent – the widget’s parent name – the name of the widget text – the text to display (this can be changed later via the text property) font – the font to use pt_size – the point size of the text to draw (defaults to 30 if None) color – the color to use when rendering the font pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

theme_section = 'Label'¶

theme_options = {'Font': '', 'Color': (1, 1, 1, 1), 'OutlineSmoothing': False, 'OutlineSize': 0, 'Size': 30, 'OutlineColor': (0, 0, 0, 1)}¶

text¶

The text to display

pt_size¶

The point size of the label’s font

list_box¶

ListBoxes make use of a ListBoxRenderer. The default ListBoxRenderer simply displays an item’s string representation. To make your own ListBoxRenderer create a class that has a render_item() method that accepts the item to be rendered and returns a widget to render.

Here is an simple example of using the ListBox widget:

class MySys(bgui.System):
        def lb_click(self, lb):
                print(lb.selected)

        def __init__(self):
                bgui.System.__init__(self)

                items = ["One", "Two", 4, 4.6]
                self.frame = bgui.Frame(self, 'window', border=2, size=[0.5, 0.5],
                        options=bgui.BGUI_DEFAULT|bgui.BGUI_CENTERED)
                self.lb = bgui.ListBox(self.frame, "lb", items=items, padding=0.05, size=[0.9, 0.9], pos=[0.05, 0.05])
                self.lb.on_click = self.lb_click

                # ... rest of __init__

class bgui.list_box.ListBoxRenderer(listbox)¶

Bases: object

Base class for rendering an item in a ListBox

Parameters:	listbox – the listbox the renderer will be used with (used for parenting)

render_item(item)¶

Creates and returns a bgui.label.Label representation of the supplied item

Parameters:	item – the item to be rendered
Return type:	bgui.label.Label

class bgui.list_box.ListBox(parent, name=None, items=[], padding=0, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', options=0)¶

Bases: bgui.widget.Widget

Widget for displaying a list of data

Parameters:

parent – the widget’s parent name – the name of the widget items – the items to fill the list with (can also be changed via ListBox.items) padding – the amount of extra spacing to put between items (can also be changed via ListBox.padding) aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

theme_section = 'ListBox'¶

theme_options = {'Border': 1, 'HighlightColor4': (0, 0, 1, 1), 'Padding': 0, 'HighlightColor2': (0, 0, 1, 1), 'HighlightColor3': (0, 0, 1, 1), 'HighlightColor1': (1, 1, 1, 1)}¶

padding = None¶

The amount of extra spacing to put between items

renderer = None¶

The ListBoxRenderer to use to display items

items¶

The list of items to display in the ListBox

progress_bar¶

class bgui.progress_bar.ProgressBar(parent, name=None, percent=1.0, sub_theme='', aspect=None, size=[1, 1], pos=[0, 0], options=0)¶

Bases: bgui.widget.Widget

A solid progress bar. Controlled via the ‘percent’ property which assumes percent as a 0-1 floating point number.

Parameters:	parent – the widget’s parent name – the name of the widget percent – the initial percent sub_theme – sub type of theme to use aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position options – various other options

theme_section = 'ProgressBar'¶

theme_options = {'BGColor2': (0, 0, 0, 1), 'FillColor4': (0.0, 0.42, 0.02, 1.0), 'FillColor1': (0.0, 0.42, 0.02, 1.0), 'BGColor1': (0, 0, 0, 1), 'FillColor3': (0.0, 0.42, 0.02, 1.0), 'BorderSize': 1, 'FillColor2': (0.0, 0.42, 0.02, 1.0), 'BGColor3': (0, 0, 0, 1), 'BorderColor': (0, 0, 0, 1), 'BGColor4': (0, 0, 0, 1)}¶

percent¶

system¶

class bgui.system.System(textlib, theme=None)¶

Bases: bgui.widget.Widget

The main gui system. Add widgets to this and then call the render() method draw the gui.

Parameters:	theme – the path to a theme directory

normalize_text = True¶

focused_widget¶

The widget which currently has “focus”

update_mouse(pos, click_state=0)¶

Updates the system’s mouse data

Parameters:	pos – the mouse position click_state – the current state of the mouse
Return type:	None

update_keyboard(key, is_shifted)¶

Updates the system’s keyboard data

Parameters:	key – the key being input is_shifted – is the shift key held down?
Return type:	None

render()¶

Renders the GUI system

Return type:	None

text¶

class bgui.text.TextLibrary¶

Bases: object

Class for handling text drawing.

load(filename)¶

draw(fontid, text)¶

dimensions(fontid, text)¶

position(fontid, x, y, z)¶

size(fontid, size, dpi)¶

text_block¶

class bgui.text_block.TextBlock(parent, name=None, text='', font=None, pt_size=None, color=None, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', overflow=1, options=0)¶

Bases: bgui.widget.Widget

Widget for displaying blocks of text

Parameters:

parent – the widget’s parent name – the name of the widget text – the text to display (this can be changed later via the text property) font – the font to use pt_size – the point size of the text to draw color – the color to use when rendering the font aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) overflow – how to handle excess text options – various other options

theme_section = 'TextBlock'¶

theme_options = {'LabelSubTheme': ''}¶

text¶

The text to display

text_input¶

This module defines the following constants:

InputText options

• BGUI_INPUT_NONE = 0
• BGUI_INPUT_SELECT_ALL = 1
• BGUI_INPUT_DEFAULT = BGUI_INPUT_NONE

class bgui.text_input.TextInput(parent, name=None, text='', prefix='', font=None, pt_size=None, color=None, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', input_options=0, options=0)¶

Bases: bgui.widget.Widget

Widget for getting text input

Parameters:

parent – the widget’s parent name – the name of the widget text – the text to display (this can be changed later via the text property) prefix – prefix text displayed before user input, cannot be edited by user (this can be changed later via the prefix property) font – the font to use pt_size – the point size of the text to draw color – color of the font for this widget aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

theme_section = 'TextInput'¶

theme_options = {'LabelSubTheme': '', 'TextColor': (1, 1, 1, 1), 'HighlightColor': (0.6, 0.6, 0.6, 0.5), 'BorderSize': 0, 'InactiveBorderSize': 0, 'InactiveHighlightColor': (0.6, 0.6, 0.6, 0.5), 'InactiveBorderColor': (0, 0, 0, 0), 'BorderColor': (0, 0, 0, 0), 'InactiveTextColor': (1, 1, 1, 1), 'FrameColor': (0, 0, 0, 0), 'InactiveFrameColor': (0, 0, 0, 0)}¶

text¶

prefix¶

on_enter_key¶

A callback for when the enter key is pressed while the TextInput has focus

select_all()¶

Change the selection to include all of the text

select_none()¶

Change the selection to include none of the text

activate()¶

deactivate()¶

swapcolors(state=0)¶

update_selection()¶

find_mouse_slice(pos)¶

calc_mouse_cursor(pos)¶

texture¶

class bgui.texture.Texture(path, interp_mode)¶

Bases: object

interp_mode¶

bind()¶

class bgui.texture.ImageTexture(image, interp_mode, caching)¶

Bases: bgui.texture.Texture

reload(image)¶

class bgui.texture.VideoTexture(video, interp_mode, repeat, play_audio)¶

Bases: bgui.texture.Texture

reload(video)¶

update()¶

play(start, end, use_frames=True, fps=None)¶

theme¶

class bgui.theme.NewSectionProxy(parser, name)¶

Bases: configparser.SectionProxy

Creates a view on a section of the specified name in parser.

class bgui.theme.Theme(file)¶

Bases: configparser.ConfigParser

path = ''¶

supports(widget)¶

Checks to see if the theme supports a given widget.

Parameters:	widget – the widget to check for support

warn_legacy(section)¶

warn_support(section)¶

video¶

class bgui.video.Video(parent, vid, name=None, play_audio=False, repeat=0, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', options=0)¶

Bases: bgui.image.Image

Widget for displaying video

Parameters:

parent – the widget’s parent name – the name of the widget vid – the video to use for the widget play_audio – play the audio track of the video repeat – how many times to repeat the video (-1 = infinite) aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

play(start, end, use_frames=True, fps=None)¶

on_finish¶

The widget’s on_finish callback

widget¶

This module defines the following constants:

Widget options

• BGUI_DEFAULT = 0
• BGUI_CENTERX = 1
• BGUI_CENTERY = 2
• BGUI_NO_NORMALIZE = 4
• BGUI_NO_THEME = 8
• BGUI_NO_FOCUS = 16
• BGUI_CACHE = 32
• BGUI_CENTERED = BGUI_CENTERX | BGUI_CENTERY

Widget overflow

• BGUI_OVERFLOW_NONE = 0
• BGUI_OVERFLOW_HIDDEN = 1
• BGUI_OVERFLOW_REPLACE = 2
• BGUI_OVERFLOW_CALLBACK = 3

Mouse event states

• BGUI_MOUSE_NONE = 0
• BGUI_MOUSE_CLICK = 1
• BGUI_MOUSE_RELEASE = 2
• BGUI_MOUSE_ACTIVE = 4

class bgui.widget.WeakMethod(f)¶

Bases: object

class bgui.widget.Animation(widget, attrib, value, time_, callback)¶

Bases: object

update()¶

class bgui.widget.ArrayAnimation(widget, attrib, value, time_, callback)¶

Bases: bgui.widget.Animation

update()¶

class bgui.widget.Widget(parent, name=None, aspect=None, size=[1, 1], pos=[0, 0], sub_theme='', options=0)¶

Bases: object

The base widget class

Parameters:	parent – the widget’s parent name – the name of the widget aspect – constrain the widget size to a specified aspect ratio size – a tuple containing the width and height pos – a tuple containing the x and y position sub_theme – name of a sub_theme defined in the theme file (similar to CSS classes) options – various other options

theme_section = 'Widget'¶

theme_options = {}¶

name = None¶

The widget’s name

frozen = None¶

Whether or not the widget should accept events

visible = None¶

Whether or not the widget is visible

z_index = None¶

The widget’s z-index. Widget’s with a higher z-index are drawn over those that have a lower z-index

on_click¶

The widget’s on_click callback

on_release¶

The widget’s on_release callback

on_hover¶

The widget’s on_hover callback

on_mouse_enter¶

The widget’s on_mouse_enter callback

on_mouse_exit¶

The widget’s on_mouse_exit callback

on_active¶

The widget’s on_active callback

parent¶

The widget’s parent

system¶

A reference to the system object

children¶

The widget’s children

position¶

The widget’s position

size¶

The widget’s size

move(position, time, callback=None)¶

Move a widget to a new position over a number of frames

Parameters:	positon – The new position time – The time in milliseconds to take doing the move callback – An optional callback that is called when he animation is complete

add_animation(animation)¶

Add the animation to the list of currently running animations

Parameters:	animation – The animation