Navigation

The d3d11gui Module

A lightweight windowing toolkit designed for DirectPython. This is somewhat similar to the old d3dgui-module, but there are some big differences. Notably the event system has changed, the rendering code has been rewritten and many widgets have been completely rewritten.

Hit Testing

For Window.hitTest().

HIT_WINDOW
HIT_CAPTION
HIT_COLLAPSE
HIT_MAXIMIZE
HIT_CLOSE
HIT_RESIZEBORDER
HIT_HELP
HIT_CLIENT

Classes

Manager

A Manager is class that manages windows. All windows must be owned by a manager. You can have many managers running simultaneously, altough they don’t know about each other and the windows can’t interact between other windows owned by another manager.

Because the Manager must keep track of all it’s windows and windows must know their manager they form circular references (and even weak references don’t solve all issues). This is why it is recommended that you call Manager.close() when your application is closing. It is not critical but it makes sure that you don’t get any resource leak warnings when debugging.

class Manager(device, window, sprite=None)
Parameters:

Creates a new Manager.

close()

Closes the manager and every window it owns. Don’t use the manager after calling this.

findWindow(arg, callback=None)
Parameters:
  • arg – Argument passed to callback.
  • callback – Function used to determine if a window should be returned. If None a default is used and windows are searched by their title.
Returns:

The found window or None.

Searches for a window. You can pass a query fuction to customize what window you want to be returned. The callback function should accept two parameters window and arg. The first is the window being tested and the second is the same as passed to findWindow(). The callback should return True if it found a satisfactory window.

#Find a window with a "Tools"-title. 
window = manager.findWindow("Tools")
getAllWindows()

Returns all windows that are owned by this manager.

getFocusWindow()

Returns the focus window or None.

getHoverWindow()

Returns the window which is currently under the mouse cursor or None.

getRootWindows()

Returns all root windows (ie. windows that don’t have a parent).

getWindowAt(x, y)

Returns the window at given coordinates or None.

onMessage(msg)

An event callback which returns True if the manager handled the message.

render(frameTime)

Renders all windows.

sprite

A d3d11x.Sprite used for drawing. Mostly used from d3d11gui.Window.onRender callbacks.

Event

A simple wrapper for d3d11.Window.getMessages() messages. Currently the only new attribute is sender. In certain situations many attributes can be None (for example non-user generated messages), in this case the only useful attribute is sender.

class Event
Event(message, sender=None) → Event

Constucts a new Event.

Attributes

sender

Sender window of the message.

Window

This is the base class for all other widgets. Don’t confuse this with d3d11.Window.

class Window(parent, rect)
Parameters:
  • parent – A Manager or another Window.
  • rect – Window rectangle. If parent is another window x and y will be interpreted as local coordinates relative to the parent window.

Creates a new Window.

addChild(child)

Adds a child window to this window.

center(xaxis=True, yaxis=True)

Centers the window inside it’s parent. If it has no parent it is centered on the srceen.

close()

Closes the window and all it’s child windows. Don’t use the window after calling this.

collapse(yes=True)

Collapses or uncollapses the window.

disable(yes=True)

Disabled or enables the Window and all it’s child windows. Disabled windows don’t receive any window messages.

getAllChildren()

Returns every child and descendant of the window. You can use the .children attribute to access immediate children.

getClientRect()

Returns the client area of the window. This is the area which excludes borders, caption etc. Always in global coordinates.

getParents()

Returns window’s parents as a list.

getRect()

Returns the window’s rectangle as a new Rect. Always in global coordinates.

getRoot()

Returns the root window of a window. This will return itself if called on a root window.

getTextRect()

This is similar to getClientRect() except that .textPad is also used when computing the area. Always in global coordinates.

giveFocus()

Gives focus to the window.

hide(yes=True)

Hides or shows the Window and all it’s child windows.

hitTest(x, y, area)
Parameters:

Returns True if the given coordinates hit the given window area. You can override this method if you want to make custom widgets. If the window is hidden this should always return False.

makeModal(yes=True)

Makes the windows modal. All other windows will be disabled. When the window is closed or makeModal(False) is called other windows will be restored to the state they were when this window was made modal.

maximize(yes=True)

Maximizes or restores the window.

onChar(event)

Called when a user types a character into a window. Note that control characters (newline, backspace etc.) are included too. This is a convenience callback, onKey() receives these messages as WM_KEYDOWN / WM_KEYUP. Only the focus window will receive this event.

onClose(event)

Called when the window is about to be closed.

onDrag(event)

Called when the user is dragging the window.

onDragBegin(event)

Called when the user starts to drag the window.

onDragEnd(event)

Called when the user stops dragging the window.

onDrop(event, other)

Called when the window has been drag-and-dropped into another window. The “target” window will receive this event.

onGetCursor(event)

Called when a mouse is moving over the window. If this returns something that evaluates to True it will be passed to d3d11.Window.setCursor().

onGetFocus(event)

Called when the window has gained focus. By default this gives focus to the root window. If you want to keep focus on your window, override this method (just an empty stub will do).

onGetToolTip(event)

Called when a tooltip string should be displayed. By default this returns self.toolTip.

onKey(event)

Called when a user presses, holds down or releases a key. Only the focus window will receive this event.

onLoseFocus(event)

Called when the window has lost focus.

onMouseButton(event)

Called when a mouse button has been pressed or released.

onMouseEnter(event)

Called when the mouse enters into the window area.

onMouseLeave(event)

Called when the mouse has left the window.

onMouseMove(event)

Called when the mouse is moving inside the window.

onMouseWheel(event)

Called when the user rotates the mouse wheel. Only the focus window will receive this event.

onRender(event)

Called when the window should draw itself.

onResize(event)

Called when the window has been resized (by user, setRect() etc.). This is also called when the window has been moved.

onResizeBegin(event)

Called when the user starts to resize the window.

onResizeEnd(event)

Called when the user has stopped resizing the window.

removeChild(child)

Removes the child from window’s children. After this the child is a root window.

resize(width, height)

Resizes the window without moving it.

setAnchor(anchor)
Parameters:
  • anchor – A 4-tuple (note that this is not a Rect) or None. If None no anchor will be used.

Sets anchor information. An anchor is a tuple of four elements which specify how the window should behave when it’s parent area is moved or resized. Element order is left, top, right, bottom. For example anchor (None, None, 10, 10) tells that right and bottom sides of the window are “anchored” and should always be 10 pixels from the parent border. Because left and top borders are not specified the size of the window will not change when the parent is resized. Another example (10, 10, 10, 10) tells that the window should always have space of 10 pixels in each direction relative to the parent. This can also cause the window to be resized when this constraint must be satisfied.

setRect(newrect)

Sets the window rectangle in global coordinates. All constraints like minSize and anchor are applied to the new rectangle so the final size might not be what you specified.

update()

Updates the window and all it’s child windows. Call this if you have changed the .minSize etc.

alpha

Alpha value of the window (from 0.0 to 1.0). Class attribute used for initialization. (R/W)

anchor

Window anchor or None. (R)

borderColor

Border color in RGBA format. (R/W)

borderSize

Width of the window border. (R/W)

buttonSize

Size of the caption buttons (close etc.) as a tuple (width, height). (R/W)

captionColor

Caption color in RGBA format. (R/W)

captionHeight

Height of the caption. If 0 no caption is used. (R/W)

children

All immediate children. (R)

collapsed

True if the window is currently collapsed. (R)

color

Background color in RGBA format. (R/W)

disabled

True if the window is currently disabled. (R)

dragged

True if the window is currently dragged by the user. (R)

hidden

True if the window is currently hidden. (R)

manager

Window’s Manager. (R)

maxSize

Maximum size of the window as a tuple (width, height). (R/W)

maximized

True if the window is currently maximized. (R)

minSize

Minimum size of the window as a tuple (width, height). (R/W)

modal

True if the window is currently in modal state. (R)

movable

If True the window can be moved by the user. (R/W)

parent

Window’s parent window. (R)

resizable

If True the window can be resized by the user. (R/W)

resizing

True if the window is currently resized by the user. (R)

text

Content text. (R/W)

textColor

Text color in RGBA format. (R/W)

textPad

Text padding in each direction (left, top, right, bottom). (R/W)

title

Caption title text. (R/W)

titleColor

Title text color in RGBA format. (R/W)

toolTip

Tooltip text. (R/W)

useClipRect

When True a scissor rectangle is used when rendering children. Only used on root windows. (R/W)

valid

True if the window has not been closed. (R)

Label

A simple widget for displaying text. If the title attribute is set the widget will display a title with a border.

class Label(parent, rect, text='', title='')

Creates a new Label.

Button

A button class.

class Button(parent, rect, text='')

Creates a new Button.

onClick(event)

Called when the user has clicked the button.

Choice

A drop-down list of choices.

class Choice(parent, rect)

Creates a new Choice.

add(item)

Adds a new choice into the control.

onChoice(event, index, item)

Called when the user has selected a value.

remove(index)

Removes a choice from the control.

choices

All choice names in the control.

selected

Index of the currently selected item.

CheckBoxGroup

A group of checkboxes.

class CheckBoxGroup(parent, rect)

Creates a new CheckBoxGroup.

add(item, checked=False)
Parameters:
  • item – Label for the checkbox.
  • checked – If True the checkbox will be initally checked.

Adds a new checkbox into the control.

check(index, value=True)

Checks or unchecks a checkbox.

onCheck(event, index, item, value)

Called when a checkbox has been checked or unchecked.

remove(index)

Removes a checkbox from the control.

boxes

All checkbox names in the control. All objects in the list have name and checked attributes.

RadioGroup

A radio group control.

class RadioGroup(parent, rect)

Creates a new RadioGroup.

add(item)

Adds a new radio button into the control.

onSelect(event, index, item)

Called when a radio item has been selected.

remove(index)

Removes a radio button from the control.

select(index)

Selects a radio button.

Image

A control for displaying images. Transparency (alpha) is supported.

class Image(parent, rect, imagepath, newsize=(0, 0), resize=True)
Parameters:
  • imagepath – Path to an image file which will be loaded into manager’s sprite.
  • newsize – The texture will be resized to this size when loading. (0, 0) means no resizing.
  • resize – If True adjustSize() will be called and the control (not the texture) will be resized. There is nothing wrong in displaying “stretched” images, but it is not usually wanted and that is why this defaults to True.

Creates a new Image.

adjustSize()

Resizes the control so that it’s pixels will map 1:1 to screen pixels. Border size is taken into account. You can call this when you have changed certain visual parameters (border size etc.).

#Width and height are changed later, they don't really matter.
image = Image(window, Rect(10, 10, 1, 1), "Textures/SomeImage.png")
#We want a perfect pixel mapping with a border.
image.borderSize = 1
#Resize the control.
image.adjustSize()
flip

A flip-argument for d3d11x.Sprite.drawRect().

Slider

A slider class.

class Slider(parent, rect)

Creates a new Slider. By default a slider increses the size of it’s rectangle so that selectors are easier to drag with a mouse. If you don’t want this you can set the class attribute: Slider.pad = (0, 0). That disables this behaviour.

#Create a "normal" slider with one selector.
slider1 = Slider(parent, Rect(10, 10, 200, 10))
slider1.range = 50
slider1.addSelector()

#Create a slider with two selector so that the user can specify a range of values.
slider2 = Slider(parent, Rect(10, 10, 200, 10))
slider2.range = 100 #0-99, 100 possible positions.
slider2.addSelector(Selector(0, 50)) #Range 0-49, 50 possible positions.
slider2.addSelector(Selector(49, 100, 99)) #Range 49-99, 50 possible positions.
addSelector(selector=None)

Adds a new Selector into the slider. If no argument is given a default selector is created.

onGetLabel(event, selector)

Called during the rendering. This should return a string that will be drawn above or under the selector. By default this returns selector.position + 1 as a string.

onSlide(event, selector)

Called when a selector has moved.

removeSelector(index)

Removes a selector.

drawConnectors

If True a line is draw between selectors if there are more than one. They are assumed to form pairs (first-second, third-fourth etc.).

range

Maximum value for all selectors, non-inclusive.

selectors

All selectors. Don’t change the list itself, but you can modify it’s items.

Selector is a helper class used by the Slider.

class Selector(start, stop, position=None)
Parameters:
  • start – Minimum index for the selector, zero based.
  • stop – Maximum index for the selector, zero based, non-inclusive.
  • position – Starting position for the selector. If None start is used.

Creates a new Selector.

dragged

True if the selector is currently dragged by the user.

position

Current position of the selector.

start

Minimum value for the selector, zero based.

stop

Maximum value for the selector, zero based, non-inclusive.

ScrollBar

A scroll bar class.

Axis flags:

SCROLL_X

Horizontal scrollbar.

SCROLL_Y

Vertical scrollbar.

class ScrollBar(parent, rect, flags=3, attach=True)
Parameters:
  • flags – A combination of scroll flags (SCROLL_X, SCROLL_Y).
  • attach – If True attach() is called automatically.

Creates a new ScrollBar.

attach()

Attaches the ScrollBar to it’s current parent window. Note that once a scrollbar has been attached to a window the scrollbar should not be removed (altough it can be hidden).

getScrollData(axis)

Returns the ScrollData from the given axis or None. The returned object is a copy and can be modified.

onScroll(event, scroller, amount)

Called when a scrollbar has been moved. By default parent’s child windows are moved when scrolling. You can override this behaviour. Also when child windows are outside the parent’s client rectangle they are hidden (for performace reasons).

scroll(amount, axis)

Scrolls a relative amount from current position.

scrollTo(position, axis)

Scrolls to a specific position.

setScrollData(data)

Sets ScrollData. Axis is taken from the data.

ScrollData is a helper class used by the ScrollBar.

class ScrollData(range, step, axis)
Parameters:
  • range – Maximum position for the scrollbar, zero based, non-inclusive.
  • step – See the attribute description.
  • axis – SCROLL_X or SCROLL_Y

Creates a new ScrollData.

copy()

Creates a new copy from self.

axis

Either SCROLL_X or SCROLL_Y.

dragged

True if the selector is currently dragged by the user.

position

Current position of the scroll bar.

range

Maximum value for the selector, zero based, non-inclusive.

step

The meaning of this value is up to the user. In the default ScrollBar.onScroll() handler this value is used to determine how much the controls are moved with each scroll.

ProgressBar

A progress bar class.

class ProgressBar(parent, rect)

Creates a new ProgressBar.

onGetLabel(event)

Called during the rendering. This should return a string that will be drawn inside the progress bar. You probably want to return different values if self.throbber is True.

position

Current position. This can be from 0.0 to 1.0 (inclusive).

throbber

If True the progress bar will be animated to show to the user that something is happening but that it is unknown how long it will take.

throbberSpeed

How fast the throbber should be moving.

throbberText

This will be returned from onGetLabel() in throbber mode.

title

This will be returned from onGetLabel() in normal mode. The string should contain one format character (%i) for an integer.

TextBox

A TextBox allows the user to type and edit text. As an implementation detail the text attribute of this class is handled by a property and getting and setting the value involves some computation overhead so using it should be avoided in speed-critical places (loops etc.). Windows clipboard operations ctrl+x/c/v are supported.

class TextBox(parent, rect, scrolling=2)
Parameters:
  • scrolling – If not 0 a scrollbar will be added. Only vertical (SCROLL_Y) scrolling is currently supported.

Creates a new TextBox.

clear()

Clears the box from all content.

eraseSelected()

Erases all selected text (if any).

getLineAt(x, y)

Returns the line index at given screen coordinates. The returned index will be clamped if outside the valid range.

getSelectedText()

Returns selected text or None if no text is selected.

getSelection()

Returns the text selection data (start, end). If no text is selected both values will be None. Otherwise they are tuples: (lineindex, charindex, xcoordinate).

insertText(text)

Inserts text at the current caret position.

onChange(event)

Called when the contents of the text box have changed. This might be called several times and in certain cases no actual changes have occurred. This can happen if the user selects text and then pastes the same text. First the selected text is erased and then the new one is inserted. The contents did change but the end result is same.

setCaret(line, index)

Moves the caret to the given position. Both arguments will be clamped if outside the valid range.

setCaretAt(x, y)

Sets the caret at the given screen coordinates.

stopSelection()

Stops text selection.

lines

A list of all lines in the control.

singleline

If True no line breaks are allowed.

Table Of Contents

Get DirectPython 11 at SourceForge.net. Fast, secure and Free Open Source software downloads

Navigation

© Copyright 2010, Heikki Salo. Last updated on Aug 09, 2010. Created using Sphinx 1.0.1.