source: libcaca/trunk/python/caca/display.py @ 4408

Last change on this file since 4408 was 4408, checked in by Alex Foulon, 11 years ago
  • Add optional pointer argument to Canvas class.
  • get_canvas method now return Python Canvas object.
  • Property svn:keywords set to Id
File size: 8.8 KB
Line 
1# -*- coding: utf-8 -*-
2#
3# libcaca       Colour ASCII-Art library
4#               Python language bindings
5# Copyright (c) 2010 Alex Foulon <alxf@lavabit.com>
6#               All Rights Reserved
7#
8# This library is free software. It comes without any warranty, to
9# the extent permitted by applicable law. You can redistribute it
10# and/or modify it under the terms of the Do What The Fuck You Want
11# To Public License, Version 2, as published by Sam Hocevar. See
12# http://sam.zoy.org/wtfpl/COPYING for more details.
13#
14
15""" Libcaca Python bindings """
16
17import ctypes
18
19from caca import _lib
20from caca.canvas import _Canvas, Canvas
21
22class _Display(object):
23    """ Model for Display objects.
24    """
25    def from_param(self):
26        """ Required by ctypes module to call object as parameter of
27            a C function.
28        """
29        return self._dp
30
31    def __str__(self):
32        return "<CacaDisplay>"
33
34    def __del__(self):
35        if self._dp > 0:
36            self._free()
37
38    def _free(self):
39        """ Free a libcaca display.
40        """
41        _lib.caca_free_display.argtypes = [_Display]
42        _lib.caca_free_display.restype  = ctypes.c_int
43
44        return _lib.caca_free_display(self)
45
46class Display(_Display):
47    """ Display objects, methods are libcaca functions with display_t as first
48        parameter.
49    """
50    def __init__(self, cv, driver=None):
51        """ Display constructor.
52
53            cv      -- canvas to attach.
54            driver  -- caca driver to set with display
55        """
56
57        if driver is None:
58            _lib.caca_create_display.argtypes = [_Canvas]
59            self._dp = _lib.caca_create_display(cv)
60        else:
61            _lib.caca_create_display_with_driver.argtypes = [
62                _Canvas, ctypes.c_char_p
63            ]
64            self._dp = _lib.caca_create_display_with_driver(cv, driver)
65
66        if self._dp == 0:
67            raise DisplayError, "Failed to create display"
68
69    def get_driver(self):
70        """ Return the caca graphical context's current output driver.
71        """
72        _lib.caca_get_display_driver.argtypes = [_Display]
73        _lib.caca_get_display_driver.restype  = ctypes.c_char_p
74
75        return _lib.caca_get_display_driver(self)
76
77    def set_driver(self, driver=None):
78        """ Set the output driver.
79
80            driver  -- A string describing the desired output driver or NULL
81                       to choose the best driver automatically.
82        """
83        _lib.caca_set_display_driver.argtypes = [_Display, ctypes.c_char_p]
84        _lib.caca_set_display_driver.restype  = ctypes.c_int
85
86        if not driver:
87            driver = ctypes.c_char_p(0)
88
89        return _lib.caca_set_display_driver(self, driver)
90
91    def get_canvas(self):
92        """ Get the canvas attached to a caca graphical context.
93        """
94        _lib.caca_get_canvas.argtypes = [_Display]
95        _lib.caca_get_canvas.restype  = ctypes.POINTER(ctypes.c_char_p)
96
97        return Canvas(pointer=_lib.caca_get_canvas(self))
98
99    def refresh(self):
100        """ Flush pending changes and redraw the screen.
101        """
102        _lib.caca_refresh_display.argtypes = [_Display]
103        _lib.caca_refresh_display.restype  = ctypes.c_int
104
105        return _lib.caca_refresh_display(self)
106
107    def set_time(self, usec):
108        """ Set the refresh delay.
109
110            usec    -- the refresh delay in microseconds
111        """
112        _lib.caca_set_display_time.argtypes = [_Display, ctypes.c_int]
113        _lib.caca_set_display_time.restype  = ctypes.c_int
114
115        return _lib.caca_set_display_time(self, usec)
116
117    def get_time(self):
118        """ Get the display's average rendering time.
119        """
120        _lib.caca_get_display_time.argtypes = [_Display]
121        _lib.caca_get_display_time.restype  = ctypes.c_int
122
123        return _lib.caca_get_display_time(self)
124
125    def set_title(self, title):
126        """ Set the display title.
127
128            title   -- the desired display title
129        """
130        _lib.caca_set_display_title.argtypes = [_Display, ctypes.c_char_p]
131        _lib.caca_set_display_title.restype  = ctypes.c_int
132
133        return _lib.caca_set_display_title(self, title)
134
135    def set_mouse(self, flag):
136        """ Show or hide the mouse pointer. This function works with the ncurses,
137        S-Lang and X11 drivers.
138
139            flag -- 0 hides the pointer, 1 shows the system's default pointer (usually an arrow).
140        """
141        _lib.caca_set_mouse.argtypes = [_Display, ctypes.c_int]
142        _lib.caca_set_mouse.restype  = ctypes.c_int
143
144        return _lib.caca_set_mouse(self, flag)
145
146    def set_cursor(self, flag):
147        """ Show or hide the cursor, for devices that support such a feature.
148
149            flag -- 0 hides the cursor, 1 shows the system's default cursor (usually a white rectangle).
150        """
151
152        _lib.caca_set_cursor.argtypes = [Display, ctypes.c_int]
153        _lib.caca_set_cursor.restype  = ctypes.c_int
154
155        return _lib.caca_set_cursor(self, flag)
156
157    def get_event(self, event_mask, event, timeout):
158        """ Poll the event queue for mouse or keyboard events matching the event mask
159        and return the first matching event. Non-matching events are discarded.
160        If event_mask is zero, the function returns immediately.
161        The timeout value tells how long this function needs to wait for an event.
162        A value of zero returns immediately and the function returns zero if no more events
163        are pending in the queue. A negative value causes the function to wait indefinitely
164        until a matching event is received.
165        If not null, ev will be filled with information about the event received. If null,
166        the function will return but no information about the event will be sent.
167
168            event_mask  -- bitmask of requested events
169            event       -- a pointer to caca_event structure or NULL
170            tiemout     -- a timeout value in microseconds
171        """
172
173        _lib.caca_get_event.argtypes = [Display, ctypes.c_int, ctypes.POINTER(Event), ctypes.c_int]
174
175        return _lib.caca_get_event(self, event_mask, ctypes.byref(event), timeout)
176
177    def get_mouse_x(self):
178        """ Return the X coordinate of the mouse position last time it was detected.
179        This function is not reliable if the ncurses or S-Lang drivers are being used,
180        because mouse position is only detected when the mouse is clicked.
181        Other drivers such as X11 work well.
182        """
183
184        _lib.caca_get_mouse_x.argtypes = [Display]
185        _lib.caca_get_mouse_x.restype  = ctypes.c_int
186
187        return _lib.caca_get_mouse_x(self)
188
189    def get_mouse_y(self):
190        """ Return the Y coordinate of the mouse position last time it was detected.
191        This function is not reliable if the ncurses or S-Lang drivers are being used,
192        because mouse position is only detected when the mouse is clicked.
193        Other drivers such as X11 work well.
194        """
195
196        _lib.caca_get_mouse_y.argtypes = [Display]
197        _lib.caca_get_mouse_y.restype  = ctypes.c_int
198
199        return _lib.caca_get_mouse_y(self)
200
201class DisplayError(Exception):
202    pass
203
204class Event(ctypes.Structure):
205    """ Object to store libcaca event.
206    """
207    _fields_ = (
208        ('opaque_structure', ctypes.c_char_p * 32),
209    )
210
211    def from_param(self):
212        """ Required method to pass object as parameter of a C function.
213        """
214        return ctypes.byref(self)
215
216    def get_type(self):
217        """ Return the type of an event. This function may always be called
218            on an event after caca_get_event() was called, and its return value
219            indicates which other functions may be called.
220        """
221        _lib.caca_get_event_type.argtypes = [Event]
222        _lib.caca_get_event_type.restype = ctypes.c_int
223
224        return _lib.caca_get_event_type(self)
225
226    def get_key_ch(self):
227        """ Return either the ASCII value for an event's key, or if the key is not
228            an ASCII character, an appropriate KEY_* value
229        """
230        _lib.caca_get_event_key_ch.argtypes = [Event]
231        _lib.caca_get_event_key_ch.restype = ctypes.c_int
232
233        return _lib.caca_get_event_key_ch(self)
234
235    def get_key_utf32(self):
236        """ Return the UTF-32/UCS-4 value for an event's key if it resolves
237            to a printable character.
238        """
239        _lib.caca_get_event_key_utf32.argtypes = [Event]
240        _lib.caca_get_event_key_utf32.restype = ctypes.c_uint32
241
242        return _lib.caca_get_event_key_utf32(self)
243
244    def get_key_utf8(self):
245        """ Write the UTF-8 value for an event's key if it resolves to a
246            printable character. Up to 6 UTF-8 bytes and a null termination
247            are written.
248        """
249        # set buffer for writing utf8 value
250        buf = ctypes.c_buffer(2)
251
252        _lib.caca_get_event_key_utf8.argtypes = [Event, ctypes.c_char_p]
253        _lib.caca_get_event_key_utf8.restype = ctypes.c_int
254
255        _lib.caca_get_event_key_utf8(self, buf)
256
257        return buf
258
Note: See TracBrowser for help on using the repository browser.