1/*
2 Copyright (C) 2009 Mobile Sorcery AB
3
4 This program is free software; you can redistribute it and/or modify it under
5 the terms of the GNU General Public License, version 2, as published by
6 the Free Software Foundation.
7
8 This program is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
11 for more details.
12
13 You should have received a copy of the GNU General Public License
14 along with this program; see the file COPYING. If not, write to the Free
15 Software Foundation, 59 Temple Place - Suite 330, Boston, MA
16 02111-1307, USA.
17*/
18
19#if !defined(MAAPI_H)
20#define MAAPI_H
21
22#include <stdint.h>
23
24#define EXTENT_Y(e) ((short)(e))
25#define EXTENT_X(e) ((short)((e) >> 16))
26#define TRANS_NONE 0
27#define FONT_TYPE_SERIF 0
28#define FONT_TYPE_SANS_SERIF 1
29#define FONT_TYPE_MONOSPACE 2
30// same values as tizen enum FontStyle
31#define FONT_STYLE_NORMAL 0x0001
32#define FONT_STYLE_BOLD 0x0002
33#define FONT_STYLE_ITALIC 0x0004
34#define HANDLE_LOCAL 0
35#define RES_OUT_OF_MEMORY -1
36#define RES_BAD_INPUT -2
37#define RES_OK 1
38#define HANDLE_SCREEN 0
39#define RES_FONT_OK 1
40#define MAK_MENU 293
41#define EVENT_TYPE_POINTER_PRESSED 8
42#define EVENT_TYPE_POINTER_RELEASED 9
43#define EVENT_TYPE_POINTER_DRAGGED 10
44#define EVENT_TYPE_KEY_PRESSED 11
45#define EVENT_TYPE_OPTIONS_BOX_BUTTON_CLICKED 41
46#define EVENT_TYPE_SCREEN_CHANGED 21
47
48#ifndef _WCHAR_DEFINED
49#define _WCHAR_DEFINED
50typedef wchar_t wchar;
51#endif //_WCHAR_DEFINED
52
53#ifndef _SYSV_TYPES_DEFINED
54#define _SYSV_TYPES_DEFINED
55typedef unsigned short ushort;
56typedef unsigned int uint;
57#endif //_SYSV_TYPES_DEFINED
58
59typedef int MAExtent;
60typedef void* MAAddress;
61typedef intptr_t MAHandle;
62
63typedef struct MARect {
64 int left;
65 int top;
66 int width;
67 int height;
68} MARect;
69
70typedef struct MAPoint2d {
71 int x;
72 int y;
73} MAPoint2d;
74
75/**
76 * \brief An event; a message indicating that something has happened, e.g. that a key has been pressed.
77 */
78typedef struct MAEvent {
79 /**
80 * One of the \link #EVENT_TYPE_CLOSE EVENT_TYPE \endlink constants.
81 */
82 int type;
83 union {
84 struct {
85 /**
86 * In KEY events, this will be one of the \link #MAK_UNKNOWN MAK \endlink constants.
87 */
88 int key;
89
90 /**
91 * In KEY events, this will be the native keycode.
92 */
93 int nativeKey;
94 };
95
96 struct {
97 /**
98 * In POINTER events, this will be the location of the pointer.
99 */
100 MAPoint2d point;
101 };
102
103 /**
104 * #EVENT_TYPE_OPTIONS_BOX_BUTTON_CLICKED event, contains the index of the selected option.
105 */
106 int optionsBoxButtonIndex;
107 };
108} MAEvent;
109
110/**
111 * Deletes a loaded font
112 * \param 'font' A font handle
113 * \return RES_FONT_OK, RES_FONT_INVALID_HANDLE, or RES_FONT_DELETE_DENIED.
114 */
115int maFontDelete(MAHandle font);
116
117/**
118 * Sets the color used by drawing functions. Returns previous color. Initial color is 0 (black).
119 * \param rgb A color in RGB8 format (0xRRGGBB). The top byte is ignored.
120 */
121int maSetColor(int rgb);
122
123/**
124 * Sets the clipping rectangle for the current draw target.
125 * The screen and every drawable image each maintains a clipping rectangle.
126 * Drawing operations have no effect outside the clipping rectangle.
127 * The default clipping rectangle covers the entire draw target, so that
128 * clipping occurs at the draw target's edges.
129 */
130void maSetClipRect(int left, int top, int width, int height);
131
132/**
133 * Draws a single pixel using the current color.
134 * \see maSetColor()
135 */
136void maPlot(int posX, int posY);
137
138/**
139 * Draws a line using the current color.
140 * \see maSetColor()
141 */
142void maLine(int startX, int startY, int endX, int endY);
143
144/**
145 * Draws an ellipse using the current color.
146 * \see maSetColor()
147 */
148void maEllipse(int xc, int yc, int rx, int ry, int fill);
149
150/**
151 * Draws an arc using the current color.
152 * \see maSetColor()
153 */
154void maArc(int xc, int yc, double r, double start, double end, double aspect);
155
156/**
157 * Draws a filled rectangle using the current color.
158 * Width and height must be greater than zero.
159 * \see maSetColor()
160 */
161void maFillRect(int left, int top, int width, int height);
162
163/**
164 * Draws Latin-1 text using the current color.
165 * The coordinates are the top-left corner of the text's bounding box.
166 * \see maSetColor()
167 */
168void maDrawText(int left, int top, const char *str, int length);
169
170/**
171 * Copies the back buffer to the physical screen.
172 */
173void maUpdateScreen(void);
174
175/**
176 * Returns the size in pixels of Latin-1 text as it would appear on-screen.
177 */
178MAExtent maGetTextSize(const char *str);
179
180/**
181 * Returns the screen size.
182 * Returns the screen size.
183 */
184MAExtent maGetScrSize(void);
185
186/**
187 * Returns a handle to one of the default fonts of the device, in the style and size you specify.
188 * \param 'type' The type of the font, can be FONT_TYPE_[SANS_SERIF,SERIF,MONOSPACE].
189 * \param 'style' The style of the font, can be FONT_STYLE_[NORMAL,BOLD,ITALIC].
190 * \param 'size' The size of the font.
191 * \return The handle to the font, RES_FONT_NO_TYPE_STYLE_COMBINATION, or RES_FONT_INVALID_SIZE.
192 */
193MAHandle maFontLoadDefault(int type, int style, int size);
194
195/**
196 * Sets the font to be used with maDrawText and maDrawTextW, and returns the handle
197 * to the previous font.
198 * \param 'font' an MAHandle for a font object.
199 * \return The handle to the previous font, or RES_FONT_INVALID_HANDLE.
200 */
201MAHandle maFontSetCurrent(MAHandle font);
202
203/**
204 * Draws an image.
205 * The source is an array of ints that represent pixels in ARGB format.
206 * \param dstPoint The top-left point on the draw target.
207 * \param src The address to the source image.
208 * \param srcRect The portion of the source image to be drawn.
209 * \param opacity
210 * \param bytesPerLine
211 */
212void maDrawRGB(const MAPoint2d *dstPoint, const void *src, const MARect *srcRect, int opacity, int bytesPerLine);
213
214/**
215 * Draws a portion of an image using a transformation.
216 * \param image The source image.
217 * \param srcRect The portion of the source image to be drawn.
218 * Must not exceed the bounds of the source image.
219 * \param dstPoint The top-left point on the draw target.
220 * \param transformMode One of the \link #TRANS_NONE TRANS \endlink constants.
221 * \see maDrawImage
222 */
223void maDrawImageRegion(MAHandle image, const MARect *srcRect, const MAPoint2d *dstPoint, int transformMode);
224
225/**
226 * Creates a drawable image of the specified size. A drawable image has no alpha channel,
227 * which is to say, no transparency.
228 * Its initial contents are undefined, so you should draw onto the entire surface to
229 * be sure what will happen when you draw this image onto something else.
230 * \param placeholder The resource handle of the new image.
231 * \param width Width, in pixels, of the new image. Must be \> 0.
232 * \param height Height, in pixels, of the new image. Must be \> 0.
233 * \see maSetDrawTarget()
234 * \returns #RES_OK if succeded and #RES_OUT_OF_MEMORY if failed.
235 */
236int maCreateDrawableImage(MAHandle placeholder, int width, int height);
237
238/**
239 * Creates a new placeholder and returns the handle to it.
240 */
241MAHandle maCreatePlaceholder(void);
242
243/**
244 * Releases a handle returned by maCreatePlaceholder().
245 * If the handle refers to an object, such as an image or a data object,
246 * that object is destroyed, as if maDestroyObject() had been called.
247 *
248 * The released handle may be reused by the system
249 * and returned by future calls to maCreatePlaceholder(),
250 * or by other system functions that allocate resources dynamically.
251 *
252 * This function is preferred to maDestroyObject(), unless you need
253 * to reuse the handle.
254 *
255 * Attempting to destroy a handle that has already been released,
256 * or was not returned by maCreatePlaceholder(), will cause a MoSync Panic.
257 *
258 * @param handle The handle to be released.
259 */
260void maDestroyPlaceholder(MAHandle handle);
261
262/**
263 * Copies an image into an array of ints that represent pixels in ARGB format.
264 * The destination rectangle is defined as { 0,0, \a srcRect.width, \a srcRect.height }.
265 * Parts of the destination array that are outside the destination rectangle are not modified.
266 * If \a srcRect is outside the bounds of the source image,
267 * or if \a srcRect.width is greater than \a scanlength, a MoSync Panic is thrown.
268 * \param image The handle to the source image.
269 * \param dst The address of the destination array.
270 * \param scanlength The width of the image, in pixels, represented by the destination array.
271 * \param srcRect The portion of the source image to be copied.
272 */
273void maGetImageData(MAHandle image, void *dst, const MARect *srcRect, int scanlength);
274
275/**
276 * Sets the current draw target.
277 * The handle must be a drawable image or #HANDLE_SCREEN, which represents the back buffer.
278 * The initial draw target is the back buffer.
279 * If an image is set as draw target, its object handle goes into flux, which prevents
280 * its destruction or use as a source in maDrawImage. When a different draw target is set,
281 * the image's handle is restored. Returns the the previously set draw target.
282 * \see maCreateDrawableImage()
283 */
284MAHandle maSetDrawTarget(MAHandle image);
285
286/**
287 * Returns the number of milliseconds that has passed since some unknown point in time.
288 * Accuracy is platform-specific, but should be better than 20 ms.
289 */
290int maGetMilliSecondCount(void);
291
292/**
293 * Shows the virtual keyboard.
294 */
295void maShowVirtualKeyboard(void);
296
297/**
298 * Hides the virtual keyboard.
299 */
300void maHideVirtualKeyboard(void);
301
302/**
303 * There is a FIFO buffer that contains up to #EVENT_BUFFER_SIZE events.
304 * Each event has a type. Some types have additional data.
305 *
306 * This function retrieves the next event, unless the queue is empty.
307 * Use maWait() to wait until more events are available.
308 * \param event Pointer to an MAEvent struct that will be filled with the next event.
309 *
310 * When the \link #EVENT_TYPE_CLOSE Close event \endlink is posted,
311 * you must call maExit as soon as possible, or
312 * your program will be forcibly terminated. The timeout is device-dependent, but
313 * never longer than #EVENT_CLOSE_TIMEOUT milliseconds.
314 *
315 * After the Close event has been posted, most syscalls will stop working,
316 * returning default values and doing nothing.
317 * Only the following groups of functions are guaranteed to remain operational:
318 * Memory management, math, Resource management, Store, time, logging, maExit() and maPanic().
319 *
320 * \note Not all platforms have the capability to generate a Close event.
321 * You must always provide another way for the user to exit your application.
322 *
323 * \returns \> 0 on success, or zero if the buffer is empty.
324 */
325int maGetEvent(MAEvent *event);
326
327/**
328 * Suspends execution until there is an event in the buffer,
329 * or \a timeout milliseconds have passed. A timeout <= 0 is considered infinite.
330 * Timer accuracy is platform-specific, but should be better than 20 ms.
331 *
332 * Use this function rather than idle loops to save CPU/battery power.
333 * \see maGetEvent()
334 */
335void maWait(int timeout);
336
337#endif
338