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

Last change on this file since 4398 was 4398, checked in by Sam Hocevar, 11 years ago

New improved ctypes-based Python bindings, by Alex Foulon <alxf@lavabit.com>.

  • Property svn:keywords set to Id
File size: 8.6 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
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    def get_driver(self):
67        """ Return the caca graphical context's current output driver.
68        """
69        _lib.caca_get_display_driver.argtypes = [_Display]
70        _lib.caca_get_display_driver.restype  = ctypes.c_char_p
71
72        return _lib.caca_get_display_driver(self)
73
74    def set_driver(self, driver=None):
75        """ Set the output driver.
76
77            driver  -- A string describing the desired output driver or NULL
78                       to choose the best driver automatically.
79        """
80        _lib.caca_set_display_driver.argtypes = [_Display, ctypes.c_char_p]
81        _lib.caca_set_display_driver.restype  = ctypes.c_int
82
83        if not driver:
84            driver = ctypes.c_char_p(0)
85
86        return _lib.caca_set_display_driver(self, driver)
87
88    def get_canvas(self):
89        """ Get the canvas attached to a caca graphical context.
90        """
91        _lib.caca_get_canvas.argtypes = [_Display]
92
93        return _lib.caca_get_canvas(self)
94
95    def refresh(self):
96        """ Flush pending changes and redraw the screen.
97        """
98        _lib.caca_refresh_display.argtypes = [_Display]
99        _lib.caca_refresh_display.restype  = ctypes.c_int
100
101        return _lib.caca_refresh_display(self)
102
103    def set_time(self, usec):
104        """ Set the refresh delay.
105
106            usec    -- the refresh delay in microseconds
107        """
108        _lib.caca_set_display_time.argtypes = [_Display, ctypes.c_int]
109        _lib.caca_set_display_time.restype  = ctypes.c_int
110
111        return _lib.caca_set_display_time(self, usec)
112
113    def get_time(self):
114        """ Get the display's average rendering time.
115        """
116        _lib.caca_get_display_time.argtypes = [_Display]
117        _lib.caca_get_display_time.restype  = ctypes.c_int
118
119        return _lib.caca_get_display_time(self)
120
121    def set_title(self, title):
122        """ Set the display title.
123
124            title   -- the desired display title
125        """
126        _lib.caca_set_display_title.argtypes = [_Display, ctypes.c_char_p]
127        _lib.caca_set_display_title.restype  = ctypes.c_int
128
129        return _lib.caca_set_display_title(self, title)
130
131    def set_mouse(self, flag):
132        """ Show or hide the mouse pointer. This function works with the ncurses,
133        S-Lang and X11 drivers.
134
135            flag -- 0 hides the pointer, 1 shows the system's default pointer (usually an arrow).
136        """
137        _lib.caca_set_mouse.argtypes = [_Display, ctypes.c_int]
138        _lib.caca_set_mouse.restype  = ctypes.c_int
139
140        return _lib.caca_set_mouse(self, flag)
141
142    def set_cursor(self, flag):
143        """ Show or hide the cursor, for devices that support such a feature.
144
145            flag -- 0 hides the cursor, 1 shows the system's default cursor (usually a white rectangle).
146        """
147
148        _lib.caca_set_cursor.argtypes = [Display, ctypes.c_int]
149        _lib.caca_set_cursor.restype  = ctypes.c_int
150
151        return _lib.caca_set_cursor(self, flag)
152
153    def get_event(self, event_mask, event, timeout):
154        """ Poll the event queue for mouse or keyboard events matching the event mask
155        and return the first matching event. Non-matching events are discarded.
156        If event_mask is zero, the function returns immediately.
157        The timeout value tells how long this function needs to wait for an event.
158        A value of zero returns immediately and the function returns zero if no more events
159        are pending in the queue. A negative value causes the function to wait indefinitely
160        until a matching event is received.
161        If not null, ev will be filled with information about the event received. If null,
162        the function will return but no information about the event will be sent.
163
164            event_mask  -- bitmask of requested events
165            event       -- a pointer to caca_event structure or NULL
166            tiemout     -- a timeout value in microseconds
167        """
168
169        _lib.caca_get_event.argtypes = [Display, ctypes.c_int, ctypes.POINTER(Event), ctypes.c_int]
170
171        return _lib.caca_get_event(self, event_mask, ctypes.byref(event), timeout)
172
173    def get_mouse_x(self):
174        """ Return the X coordinate of the mouse position last time it was detected.
175        This function is not reliable if the ncurses or S-Lang drivers are being used,
176        because mouse position is only detected when the mouse is clicked.
177        Other drivers such as X11 work well.
178        """
179
180        _lib.caca_get_mouse_x.argtypes = [Display]
181        _lib.caca_get_mouse_x.restype  = ctypes.c_int
182
183        return _lib.caca_get_mouse_x(self)
184
185    def get_mouse_y(self):
186        """ Return the Y coordinate of the mouse position last time it was detected.
187        This function is not reliable if the ncurses or S-Lang drivers are being used,
188        because mouse position is only detected when the mouse is clicked.
189        Other drivers such as X11 work well.
190        """
191
192        _lib.caca_get_mouse_y.argtypes = [Display]
193        _lib.caca_get_mouse_y.restype  = ctypes.c_int
194
195        return _lib.caca_get_mouse_y(self)
196
197class Event(ctypes.Structure):
198    """ Object to store libcaca event.
199    """
200    _fields_ = (
201        ('opaque_structure', ctypes.c_char_p * 32),
202    )
203
204    def from_param(self):
205        """ Required method to pass object as parameter of a C function.
206        """
207        return ctypes.byref(self)
208
209    def get_type(self):
210        """ Return the type of an event. This function may always be called
211            on an event after caca_get_event() was called, and its return value
212            indicates which other functions may be called.
213        """
214        _lib.caca_get_event_type.argtypes = [Event]
215        _lib.caca_get_event_type.restype = ctypes.c_int
216
217        return _lib.caca_get_event_type(self)
218
219    def get_key_ch(self):
220        """ Return either the ASCII value for an event's key, or if the key is not
221            an ASCII character, an appropriate KEY_* value
222        """
223        _lib.caca_get_event_key_ch.argtypes = [Event]
224        _lib.caca_get_event_key_ch.restype = ctypes.c_int
225
226        return _lib.caca_get_event_key_ch(self)
227
228    def get_key_utf32(self):
229        """ Return the UTF-32/UCS-4 value for an event's key if it resolves
230            to a printable character.
231        """
232        _lib.caca_get_event_key_utf32.argtypes = [Event]
233        _lib.caca_get_event_key_utf32.restype = ctypes.c_uint32
234
235        return _lib.caca_get_event_key_utf32(self)
236
237    def get_key_utf8(self):
238        """ Write the UTF-8 value for an event's key if it resolves to a
239            printable character. Up to 6 UTF-8 bytes and a null termination
240            are written.
241        """
242        # set buffer for writing utf8 value
243        buf = ctypes.c_buffer(2)
244
245        _lib.caca_get_event_key_utf8.argtypes = [Event, ctypes.c_char_p]
246        _lib.caca_get_event_key_utf8.restype = ctypes.c_int
247
248        _lib.caca_get_event_key_utf8(self, buf)
249
250        return buf
251
Note: See TracBrowser for help on using the repository browser.