# $Id: Constants.py,v 1.32.2.5 2007/01/28 11:24:30 marcusva Exp $ # # Copyright (c) 2004-2006, Marcus von Appen # All rights reserved. # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # * Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE # POSSIBILITY OF SUCH DAMAGE. """Constants used by the ocempgui widgets module. General constants ----------------- General constants denote values, which are used for multiple purposes and usually not limited to specific widget class parts. DEFAULTDATADIR Path to the directory where theme files and additional resources were installed. This path is especially important for the Style class and user code, which relies upon the drawing engines or other resources. State constants --------------- The state constants denote the state of a widget and influence its behaviour and appeareance. They usually can be read from the widget through its 'state' attribute and are usually prefixed with 'STATE_'. The state constants are grouped in the STATE_TYPES tuple. STATE_NORMAL The usual state ('default') of a widget. This is the basic state, the widget has, if it is created and no interaction happened with it. STATE_ENTERED The widget area was entered by a pointing device. This usually slightly changes the visual appearance of the widget, so it is easier to distinguish between the entered and other widgets. STATE_ACTIVE The widget is activated. This usually will cause a widget to change its visual appearance, so the user can see the interaction. A Button widget for example will be drawn in a sunken state, while an Entry widget will show a blinking caret. STATE_INSENSITIVE Usually set through the 'sensitive' attribute of a widget. This will change the visual appearance of the widget, so that it is easier to distinguish between widgets, with which an interaction is possible and insensitive widgets, with which it is not. Scrolling constants ------------------- The scrolling constants only apply to widgets, which support scrolling such as the ScrolledList or ScrolledWindow classes. They influence the visibility and behaviour of the attached scrollbars for those widgets. The scrolling constants are grouped in the SCROLL_TYPES tuple. SCROLL_NEVER Scrollbars will never be shown, independant of if they are necessary or not. SCROLL_AUTO Scrollbars will be shown and hidden on demand. SCROLL_ALWAYS Scrollbars will always be shown, independant of if they are necessary or not. Selection constants ------------------- Selection constants influence the selection behaviour in the list and tree like widgets such as the ScrolledList class. The selection constants are grouped in the SELECTION_TYPES tuple. SELECTION_NONE No selection is possible. Elements cannot be selected and existing selections can not be changed. SELECTION_SINGLE Only one element can be selected per time. SELECTION_MULTIPLE Multiple elements can be selected. Border constants ---------------- The border constants influence the appearance of a widget border. Several widgets support this constants to fit in their environment. The border constants are grouped in the BORDER_TYPES tuple. BORDER_NONE The widget will have no visible border. BORDER_FLAT The widget will have a flat border around it. BORDER_SUNKEN The widget will have a sunken border effect. BORDER_RAISED The widget will have a raised border effect. BORDER_ETCHED_IN The widget will have a etched in border effect. BORDER_ETCHED_OUT The widget will have a etched out border effect. Arrow constants --------------- The arrow constants are used by the ScrollBar widgets and determine the direction of the arrows on the scrollbar buttons. The arrow constants are grouped in the ARROW_TYPES tuple. ARROW_UP The arrow points upwards. ARROW_DOWN The arrown points downwards ARROW_LEFT The arrow points to the left. ARROW_RIGHT The arrow points to the right. Alignment flags --------------- The alignment flags are used by most Container and Bin widget classes and influence the drawing positions of the attached children. The flags can be combined bitwise, although not every combination makes sense (like ALIGN_TOP | ALIGN_BOTTOM). The alignment flags are grouped in the ALIGN_TYPES tuple. ALIGN_NONE No special alignment, use the defaults of the widget. ALIGN_TOP Align the child(ren) at the top. ALIGN_BOTTOM Align the child(ren) at the bottom. ALIGN_LEFT Align the child(ren) at the left side. ALIGN_RIGHT Align the child(ren) at the right side. Orientation types ----------------- The orientation types are used by widgets, which are able to draw themselves in a vertical or horizontal alignment, such as Diagram or Scale widgets. A single axis chart for example can have either a vertical or horizontal axis orientation. The orientation constance are grouped in the ORIENTATION_TYPES tuple. ORIENTATION_VERTICAL The widget parts are aligned and drawn vertically. ORIENTATION_HORIZONTAL The widget parts are align and drawn horizontally. Dialog result values -------------------- Dialog result values are used and sent by dialog windows, which inherit from the GenericDialog, only. They usually represent the button of the dialog, that got pressed and allow to react upon the user input action. The dialog result constants are grouped in the DLGRESULT_TYPES tuple. The descriptions of the results below are meant as usability guidelines. The average user mostly will have the described intention, when he presses a button with that result value. DLGRESULT_OK Indicates, that the user agrees to or accepts the information shown on the dialog or successfully finished her input. DLGRESULT_CANCEL Indicates, that the user wants to abort from the current action or input without making any changes to the current state. DLGRESULT_ABORT Same as above, but mostly used in a different context such as a hard program or process abort. DLGRESULT_CLOSE Used in dialogs, in which usually no special agreement of the user is needed. Mostly used for dialogs, that show information only and do not influence the application behaviour in any way. DLGRESULT_USER Freely choosable. Signal constants ---------------- The signal constants denote various event identfies, which are emitted on and by widgets and to which widgets can listen. Usually there is a distinction between native signal (those which are emitted by the pygame library) and widget signals (those which are emitted by widgets). The native signals are usually just aliases for pygame constants to fit in the OcempGUI namespace. Signal callbacks for native signals usually will receive the pygame event data as first argument. This means, that a callback would look like the following: widget.connect_signal (SIG_MOUSEDOWN, mousedown_callback, owndata) def mousedown_callback (eventdata, userdata1, ...): if eventdata.pos == ...: ... if userdata1 == owndata: ... The passed pygame event data matches the sent pygame.event.Event data for the specific signal as described in the pygame documentation. SIG_KEYDOWN Alias for pygame.locals.KEYDOWN. Emitted, if a key on the keyboard will be pressed down. OcempGUI uses a repeatedly emittance of that event by the pygame.key.set_repeat() function. Note: Signal callbacks will receive the pygame event data as first argument. SIG_KEYUP Alias for pygame.locals.KEYUP. Emitted, if a key on the keyboard is released. Note: Signal callbacks will receive the pygame event data as first argument. SIG_MOUSEDOWN Alias for pygame.locals.MOUSEBUTTONDOWN. Emitted, if a mouse button gets pressed (or the mouse wheel is used). Note: Signal callbacks will receive the pygame event data as first argument. SIG_MOUSEUP Alias for pygame.locals.MOUSEBUTTONUP, Emitted, if a mouse button is released. Note: Signal callbacks will receive the pygame event data as first argument. SIG_MOUSEMOVE Alias for pygame.locals.MOUSEMOTION. Emitted, if the mouse cursor position changes (the mouse is moved). Note: Signal callbacks will receive the pygame event data as first argument. SIG_TICK Alias for pygame.locals.USEREVENT + 1. This is a timer event for widgets, which need timed event emits such as the Entry widget class (blinking cursor) or the StatusBar (date update). Usually this event is emitted every 500ms by the Renderer class. SIG_TWISTED Alias for pygame.locals.USEREVENT + 2. This signal type is used only by the TwistedRenderer at the moment and will be sent whenever the interleave() method of its attached reactor is called. SIG_UPDATED Alias for pygame.locals.USEREVENT + 3. This signal is used by the Renderer class to notify listeners about an update of the screen area. SIG_SCREENCHANGED Alias for pygame.locals.USEREVENT + 4. This signal type is used by the Renderer class to notify listeners about changes of the attached screen area. SIG_CLICKED Raised by supporting widgets, if the following event sequence happens on the widget: 1) Left mouse button pressed down (SIG_MOUSEDOWN). 2) Left mouse button released (SIG_MOUSEUP) 3) Click event will be raised by the widget (SIG_CLICKED). SIG_FOCUSED Raised by supporting widgets, if a widget is focused by the mouse or another input device (such as the keyboard). This usually will pass the input focus to that widget. SIG_INPUT Raised by widgets, which support data input and indicates, that an made input was successfully finished. An example would be the Editable widget class, which raises SIG_INPUT upon pressing Enter/Return after typing text. SIG_TOGGLED Raised by widgets, which support and/or indicate True/False value states such as the Check- or ToggleButton. This will be raised _after_ the value has been changed. SIG_VALCHANGED Raised, if the main value of a supporting widget changed (usually numeric), such as the value of a Scale or ProgressBar. SIG_SELECTCHANGED Raised, if a certain selection changed. SIG_LISTCHANGED Raised if the attached item list of a ScrolledList changed. SIG_DIALOGRESPONSE Raised, when a button attached to a GenericDialog object gets pressed. Note: Signal callbacks will receive the result value bound to the button as first argument. SIG_DESTROYED Raised by a widget, when it is about to be destroyed. Note: Signal callbacks will receive the destroyed widget as first argument. SIG_ENTER Raised by a widget, when the mouse cursor enters it. SIG_LEAVE Raised by a widget, when the mouse cursor leaves it. """ from pygame import KEYDOWN, KEYUP, MOUSEBUTTONDOWN, MOUSEMOTION, MOUSEBUTTONUP from pygame import USEREVENT # State constants. STATE_NORMAL = 0 STATE_ENTERED = 1 STATE_ACTIVE = 2 STATE_INSENSITIVE = 3 STATE_TYPES = (STATE_NORMAL, STATE_ENTERED, STATE_ACTIVE, STATE_INSENSITIVE) # Srolling behaviour widget widgets, which support it. SCROLL_NEVER = 0 SCROLL_AUTO = 1 SCROLL_ALWAYS = 2 SCROLL_TYPES = (SCROLL_NEVER, SCROLL_AUTO, SCROLL_ALWAYS) # Selection modes. SELECTION_NONE = 0 SELECTION_SINGLE = 1 SELECTION_MULTIPLE = 2 SELECTION_TYPES = (SELECTION_NONE, SELECTION_SINGLE, SELECTION_MULTIPLE) # Border types. BORDER_NONE = 0 BORDER_FLAT = 1 BORDER_SUNKEN = 2 BORDER_RAISED = 3 BORDER_ETCHED_IN = 4 BORDER_ETCHED_OUT = 5 BORDER_TYPES = (BORDER_NONE, BORDER_FLAT, BORDER_SUNKEN, BORDER_RAISED, BORDER_ETCHED_IN, BORDER_ETCHED_OUT) # Arrow types. ARROW_UP = 0 ARROW_DOWN = 1 ARROW_LEFT = 2 ARROW_RIGHT = 3 ARROW_TYPES = (ARROW_UP, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT) # Alignment types. ALIGN_NONE = 0 ALIGN_TOP = 1 << 0 ALIGN_BOTTOM = 1 << 1 ALIGN_LEFT = 1 << 2 ALIGN_RIGHT = 1 << 3 ALIGN_TYPES = (ALIGN_NONE, ALIGN_TOP, ALIGN_BOTTOM, ALIGN_LEFT, ALIGN_RIGHT) def constants_is_align (align): """C.constants_is_align (align) -> bool Checks whether the passed value evaluates to an align value. """ if type (align) != int: raise TypeError ("align must be an integer.") return (align & ALIGN_TOP == ALIGN_TOP) or \ (align & ALIGN_BOTTOM == ALIGN_BOTTOM) or \ (align & ALIGN_LEFT == ALIGN_LEFT) or \ (align & ALIGN_RIGHT == ALIGN_RIGHT) or \ (align & ALIGN_NONE == ALIGN_NONE) # Orientation types. ORIENTATION_VERTICAL = intern ("vertical") ORIENTATION_HORIZONTAL = intern ("horizontal") ORIENTATION_TYPES = (ORIENTATION_VERTICAL, ORIENTATION_HORIZONTAL) # Dialog results. DLGRESULT_OK = 0 DLGRESULT_CANCEL = 1 DLGRESULT_ABORT = 2 DLGRESULT_CLOSE = 3 DLGRESULT_USER = 99 DLGRESULT_TYPES = (DLGRESULT_OK, DLGRESULT_CANCEL, DLGRESULT_ABORT, DLGRESULT_CLOSE, DLGRESULT_USER) # Signal constants, native. SIG_KEYDOWN = KEYDOWN SIG_KEYUP = KEYUP SIG_MOUSEDOWN = MOUSEBUTTONDOWN SIG_MOUSEMOVE = MOUSEMOTION SIG_MOUSEUP = MOUSEBUTTONUP SIG_TICK = USEREVENT + 1 SIG_TWISTED = USEREVENT + 2 SIG_UPDATED = USEREVENT + 3 SIG_SCREENCHANGED = USEREVENT + 4 # Signal groups for fast tests. SIGNALS_KEYS = (SIG_KEYDOWN, SIG_KEYUP) SIGNALS_MOUSE = (SIG_MOUSEDOWN, SIG_MOUSEMOVE, SIG_MOUSEUP) # Signal constants, raised by the widgets. SIG_ACTIVATED = intern ("activated") SIG_CLICKED = intern ("clicked") SIG_FOCUSED = intern ("focused") SIG_INPUT = intern ("input") SIG_TOGGLED = intern ("toggled") SIG_VALCHANGED = intern ("value-changed") SIG_SELECTCHANGED = intern ("selection-changed") SIG_LISTCHANGED = intern ("list-changed") SIG_DOUBLECLICKED = intern ("double-clicked") SIG_DIALOGRESPONSE = intern ("dialog-response") SIG_DESTROYED = intern ("destroyed") SIG_ENTER = intern ("entered") SIG_LEAVE = intern ("left") # The default data directory, where the themes and co. get installed. # @DATAPATH@ will be replaced at installation usually. DEFAULTDATADIR = "@DATAPATH@"