Widget Classes ============== The libavg.widget module contains high-level user interface elements such as buttons and list boxes. Widgets are fully skinnable (using the :py:class:`Skin` class and an xml configuration file) and multitouch-enabled. Sample code for all widgets can be found in the :samp:`widget.py` sample. .. note:: The widget module is experimental. Functionality and interface are still in flux and subject to change. .. automodule:: libavg.widget :no-members: .. inheritance-diagram:: SwitchNode Button TextButton BmpButton ToggleButton CheckBox BmpToggleButton Keyboard Slider ScrollBar ProgressBar ScrollArea ScrollPane TimeSlider MediaControl :parts: 1 .. inheritance-diagram:: HStretchNode VStretchNode HVStretchNode Skin :parts: 1 .. autoclass:: BmpButton(upSrc, downSrc, [disabledSrc=None]) A :py:class:`Button` that is created from image files. Internally, it creates two or three :py:class:`ImageNode` s and uses them as constructor parameters for :py:class:`Button`. .. autoclass:: BmpToggleButton(uncheckedUpSrc, uncheckedDownSrc, checkedUpSrc, checkedDownSrc, [uncheckedDisabledSrc=None, checkedDisabledSrc=None]) A :py:class:`ToggleButton` that is created from image files. Internally, it creates image nodes for the src parameters and uses them as constructor parameters for :py:class:`ToggleButton`. .. autoclass:: Button(upNode, downNode, [disabledNode=None, activeAreaNode=None, fatFingerEnlarge=False, enabled=True]) A button that shows different user-supplied nodes depending on its state. Possible button states are up, down and disabled. The nodes are attached as children to the Button on construction. For a simple button, image nodes can be passed. Uses the :py:class:`TapRecognizer` to detect clicks. .. image:: ButtonStates.png :param avg.Node upNode: The node displayed when the button is not pressed. :param avg.Node downNode: The node displayed when the button is pressed. :param avg.Node disabledNode: The node displayed when the button is disabled. :param avg.Node activeAreaNode: A node that is used only to determine if a click is over the button. Usually, this node is invisible. :py:attr:`activeAreaNode` is useful for small touch buttons, where the active area should be larger than the visible button to account for touch inaccuracies. :param bool fatFingerEnlarge: If this parameter is set to :py:const:`True`, the button generates its own internal :py:attr:`activeAreaNode` that is at least 20x20mm large. :py:attr:`fatFingerEnlarge` is incompatible with a custom :py:attr:`activeAreaNode`. **Messages:** To get these messages, call :py:meth:`Publisher.subscribe`. .. py:method:: Button.PRESSED() Called when a tap on the button is initiated. .. py:method:: Button.RELEASED() Called when a tap on the button ends. Emitted for both successful and aborted taps. .. py:method:: Button.CLICKED() Called when the button is clicked. .. py:attribute:: enabled :py:const:`True` if the button accepts input. If the button is disabled, it shows the :py:attr:`disabledNode`. .. autoclass:: CheckBox([text="", skinObj=skin.Skin.default]) This is a classic checkbox with text to the right. .. autoclass:: HStretchNode(endsExtent, [src=None, minExtent=-1]) A node that stretches its graphics to fill the size given horizontally. It is used as base component for scrollbars and buttons. The base bitmap is split into three parts: left, center and right. The left and right parts are :py:attr:`endsExtent` wide and generated from the corresponding parts of the source bitmap. The center part is generated from a one pixel wide slice of the source bitmap and stretched to fill the space left between the left and right parts. :param int endsExtent: Width of the left and right bitmaps in pixels. :param src: Either the name of a bitmap file or a :py:class:`Bitmap` object. Used to generate the graphics used. :param int minExtent: Minimum horizontal size. The default of -1 uses :py:const:`2*endsExtent+1` as minimum. .. autoclass:: HVStretchNode(endsExtent, [src=None, minExtent=-(1,-1)]) A node that stretches its graphics to fill the size given horizontally and vertically. It is used as base component for scrollareas. Similar to :py:class:`HStretchNode`, the base bitmap is split and partial bitmaps are extracted. Four corner bitmaps of size :py:attr:`endsExtent` stay the same size, four one-pixel-slice bitmaps fill the sides, and a single one-pixel bitmap is used to fill the center area. :param IntPoint endsExtent: Size of the corner bitmaps in pixels. :param src: Either the name of a bitmap file or a :py:class:`Bitmap` object. Used to generate the graphics used. :param IntPoint minExtent: Minimum size. The default of :py:const:`(-1,-1]` uses :py:const:`2*endsExtent+1` as minimum. .. autoclass:: Keyboard(bgSrc, downSrc, keyDefs, shiftKeyCode, [altGrKeyCode=None, stickyShift=False, feedbackSrc=None]) Implements an onscreen keyboard that turns mouse clicks or touches into key presses. The keyboard is completely configurable. Keyboard graphics are determined by the two image files in :py:attr:`bgSrc` and :py:attr:`downSrc`. Keys can be defined as rectangles anywhere on these images. Works for both single-touch and multitouch devices. Generates events when keys are pressed or released. An additional enlarged image of the key being pressed can be rendered above a pending touch as well by using :py:attr:`feedbackSrc`. Needs offscreen rendering support on the machine to generate individual key images from the image files supplied. :param string bgSrc: Filename of an image that contains the keyboard with unpressed keys. :param string downSrc: Filename of an image that contains the keyboard with pressed keys. :param list keyDefs: List of key definitions. Keys can be either character keys: [(, , ), , , , ] or command keys: [, , , , ] For character keys, the shift and altgr keycodes are optional. To define entire rows of evenly-spaced keys, use :py:meth:`makeRowKeyDefs`. :param shiftKeyCode: One of the command keycodes. When a key with this code is pressed, pressing other keys causes them to return the shifted keycode. :param altGrKeyCode: One of the command keycodes. When a key with this code is pressed, pressing other keys causes them to return the altgr keycode. :param bool stickyShift: For single-touch devices, the shift key must stay in the pressed state until the next normal key is pressed to have any effect. This is the behaviour if :py:attr:`stickyShift` is :py:const:`True`. If it is :py:const:`False` (the default), a multitouch device is assumed and shift works like on a physical keyboard. :param string feedbackSrc: Filename of an image that contains an enlarged version of bgSrc for use as feedback during key pressed. If this parameter not set the feedback funktion is turned off. **Messages:** :py:class:`Keyboard` emits messages on every key press and release: To get these messages, call :py:meth:`Publisher.subscribe`. .. py:method:: DOWN(keycode) Emitted whenever a key (command or char) is pressed. .. py:method:: UP(keycode) Emitted whenever a key (command or char) is released. .. py:method:: CHAR(char) Emitted whenever a character is generated. This is generally when a char key is released and takes into account shift/altgr status. .. py:method:: reset() Resets any sticky keys (shift, altgr) to their default state. .. py:classmethod:: makeRowKeyDefs(startPos, keySize, spacing, feedbackStr, keyStr, shiftKeyStr, [altGrKeyStr]) Creates key definitions for a row of uniform keys. Useful for creating the keyDefs parameter of the Keyboard constructor. All the keys get no repeat functionality. :param avg.Point2D startPos: Top left position of the row. :param avg.Point2D keySize: Size of each key. :param int spacing: Number of empty pixels between two keys. :param string keyStr: Unicode string containing the unshifted keycodes (i.e. :samp:`u"qwertzuiopżś"`) :param string shiftKeyStr: Unicode string containing the shifted keycodes (i.e. :samp:`u"QWERTZUIOPńć"`) :param string altGrKeyStr: Unicode string containing the keycodes when altgr is pressed. .. autoclass:: MediaControl([duration=1000, time=0, skinObj=skin.Skin.default]) A composite control that incorporates a :py:class:`Slider`, a play/pause button and text widgets that display the time. By itself, the :py:class:`MediaControl` is independent of a media node. The controlling application is responsible for keeping track of media node and :py:class:`MediaControl` state and syncing the two. **Messages:** .. py:method:: PLAY_CLICKED() Emitted when the play/pause toggle is switched to play. .. py:method:: PAUSE_CLICKED() Emitted when the play/pause toggle is switched to pause. .. py:method:: SEEK_PRESSED() Emitted when the user starts dragging the seek thumb. .. py:method:: SEEK_MOTION(curTime) Emitted when the user moves the seek thumb. .. py:method:: SEEK_RELEASED() Emitted when the user releases the seek thumb. .. py:attribute:: duration Duration of the medium in milliseconds. .. py:attribute:: time Current media time in milliseconds. .. py:method:: play() Switches to play mode by toggling the button. .. py:method:: pause() Switches to pause mode by toggling the button. .. autoclass:: Orientation() .. py:data:: HORIZONTAL .. py:data:: VERTICAL .. autoclass:: ProgressBar(orientation, [skinObj=skin.Skin.default, height=0, width=0, range=(0.,1.), value=0.0]) A horizontal bar-shaped UI element that indicates the progression of an operation. .. py:attribute:: range Tuple giving minimum and maximum value. .. py:attribute:: value Current progression. The application is responsible for updating the value. In general, :py:attr:`value` will start at :py:attr:`range[0]` and end with :py:attr:`range[1]`. .. autoclass:: ScrollArea(contentNode, size[, skinObj=skin.Skin.default, enabled=True, scrollBars=(Orientation.HORIZONTAL, Orientation.VERTICAL)]) A rectangular area that allows a user to choose a view into arbitrary content. The content can be larger than the :py:class:`ScrollArea`, in which case scroll bars can be used to allow the user to choose which part to view. Dragging the content to determine the viewport is also supported. A :py:class:`ScrollArea` uses :py:class:`ScrollPane` and :py:class:`ScrollBar` objects internally. **Messages:** To get these messages, call :py:meth:`Publisher.subscribe`. .. py:method:: PRESSED() Emitted when a content drag is initiated. .. py:method:: RELEASED() Emitted when a content drag is finished. .. py:method:: CONTENT_POS_CHANGED(pos) Emitted when the viewport changes for any reason. .. py:attribute:: contentsize The size of the :py:attr:`contentNode`. .. py:attribute:: contentpos The position of the content within the area. .. autoclass:: ScrollBar([orientation=Orientation.HORIZONTAL, skinObj=skin.Skin.default, enabled=True, height=0, width=0, range=(0.,1.), thumbPos=0.0, thumbExtent=0.1]) A vertical or horizontal scroll bar. **Messages:** To get these messages, call :py:meth:`Publisher.subscribe`. .. py:method:: PRESSED() Emitted when a drag is initiated. .. py:method:: RELEASED() Emitted when a drag is finished. .. py:method:: THUMB_POS_CHANGED(pos) Emitted when the thumb is dragged. .. py:attribute:: range Minimum and maximum values for the thumb. .. py:attribute:: thumbPos .. py:attribute:: thumbExtent .. autoclass:: ScrollPane(contentNode) A rectangular view into arbitrary content. No user interaction is implemented. .. py:attribute:: contentpos .. py:attribute:: contentsize .. autoclass:: Skin(skinXmlFName[, mediaDir=""]) A :py:class:`Skin` determines the appearance of any user interface elements that use it. Skin configuration is determined by an xml file. This xml file determines the bitmaps to use and the sizes of various components. It also determines the fonts used by the elements. Skinnable user interface elements include :py:class:`TextButton`, :py:class:`Slider`, :py:class:`ScrollBar`, :py:class:`ProgressBar`, :py:class:`ScrollArea`, :py:class:`CheckBox` and :py:class:`MediaControl`. In addition, the fonts defined can be accessed by the application. The default skin xml file is located at :samp:`src/python/data/SimpleSkin.xml`. It provides a good basis from which to create your own skin. :param string skinXmlFName: The name of the xml configuration file. :param string mediaDir: The location of the image files to use. .. py:attribute:: fonts: A dictionary of :py:class:`FontStyle` objects created from the xml configuration file. .. autoclass:: Slider([orientation=Orientation.HORIZONTAL, skinObj=skin.Skin.default]) Sliders are horizontal or vertical bar with a draggable thumb that can be used to set a value. In contrast to a scroll bar, the slider's thumb has no range. **Messages:** To get these messages, call :py:meth:`Publisher.subscribe`. .. py:method:: PRESSED() Emitted when a drag is initiated. .. py:method:: RELEASED() Emitted when a drag is finished. .. py:method:: THUMB_POS_CHANGED(pos) Emitted when the thumb is dragged. .. py:attribute:: range Minimum and maximum values for the thumb. .. py:attribute:: thumbPos .. autoclass:: SwitchNode([nodeMap=None, visibleid=None]) A :py:class:`DivNode` that keeps a map of child nodes and shows only one of the map members at any time. :param map nodeMap: A map :py:const:`id->node` that contains the nodes to switch between. .. py:method:: setNodeMap(nodeMap) Can be used to set the :py:attr:`nodeMap` after construction if no node map was set before. .. py:attribute:: visibleid The id of the visible child node. .. autoclass:: TextButton(text, [skinObj=skin.Skin.default]) A :py:class:`Button` that is created using the given :py:class:`Skin` and a text. .. py:attribute:: text The string displayed on the button. .. autoclass:: TimeSlider() Works like a :py:class:`ProgressBar` with an additional slider thumb. .. autoclass:: ToggleButton(uncheckedUpNode, uncheckedDownNode, checkedUpNode, checkedDownNode, [uncheckedDisabledNode=None, checkedDisabledNode=None, activeAreaNode=None, fatFingerEnlarge=False, enabled=True, checked=False]) A button that can be used to toggle between checked and unchecked states. Classical GUI checkboxes are an example of this kind of button. A :py:class:`ToggleButton` has a total of six visual states. In addition to the distinction between checked and unchecked, a button can be enabled or disabled. Buttons also change their appearance as soon as they are touched, leading to two further states. For each visual state, a node is passed as constructor parameter. The constructor attaches the nodes to the :py:class:`ToggleButton`. Uses the :py:class:`TapRecognizer` to detect clicks. .. image:: ToggleButtonStates.png :param avg.Node uncheckedUpNode: The node displayed when the button is unchecked and not touched. :param avg.Node uncheckedDownNode: The node displayed when the button is unchecked and touched. :param avg.Node checkedUpNode: The node displayed when the button is checked and not touched. :param avg.Node checkedDownNode: The node displayed when the button is checked and not touched. :param avg.Node uncheckedDisabledNode: The node displayed when the button is unchecked and disabled. :param avg.Node checkedDisabledNode: The node displayed when the button is checked and disabled. :param avg.Node activeAreaNode: A node that is used only to determine if a click is over the button. Usually, this node is invisible. :py:attr:`activeAreaNode` is useful for small touch buttons, where the active area should be larger than the visible button to account for touch inaccuracies. :param bool fatFingerEnlarge: If this parameter is set to :py:const:`True`, the button generates its own internal :py:attr:`activeAreaNode` that is at least 20x20mm large. :py:attr:`fatFingerEnlarge` is incompatible with a custom :py:attr:`activeAreaNode`. :param bool checked: If this parameter is set to :py:const:`True`, the button starts in the checked state. :param bool enabled: If this parameter is set to :py:const:`True`, the button starts in the disabled state. **Messages:** To get these messages, call :py:meth:`Publisher.subscribe`. .. py:method:: Button.PRESSED() Called when a tap on the button is initiated. .. py:method:: Button.RELEASED() Called when a tap on the button ends. Emitted for both successful and aborted taps. .. py:method:: Button.TOGGLED() Called when the button changes from unchecked to checked or vice-versa. .. py:attribute:: checked The state of the toggle. .. py:attribute:: enabled Determines whether the button accepts input. .. autoclass:: VStretchNode(endsExtent, [src=None, minExtent=-1]) A node that stretches its graphics to fill the size given vertically. It is used as base component for scrollbars. The base bitmap is split into three parts: top, center and bottom. The top and bottom parts are :py:attr:`endsExtent` wide and generated from the corresponding parts of the source bitmap. The center part is generated from a one pixel high slice of the source bitmap and stretched to fill the space left between the top and bottom parts. :param int endsExtent: Width of the top and bottom bitmaps in pixels. :param src: Either the name of a bitmap file or a :py:class:`Bitmap` object. Used to generate the graphics used. :param int minExtent: Minimum vertical size. The default of :py:const:`-1` uses :py:const:`2*endsExtent+1` as minimum.