Move the gestalt_DateTime selector documentation
[projects/chimara/chimara.git] / libchimara / gestalt.c
1 #include <stddef.h> /* Surprisingly, the only symbol needed is NULL */
2 #include <config.h>
3 #include "glk.h"
4
5 /* Version of the Glk specification implemented by this library */
6 #define MAJOR_VERSION 0
7 #define MINOR_VERSION 7
8 #define SUB_VERSION   2
9
10 /**
11  * glk_gestalt:
12  * @sel: A selector, representing which capability to request information 
13  * about.
14  * @val: Extra information, depending on the value of @sel.
15  *
16  * Calls the gestalt system to request information about selector @sel, without
17  * passing an array to store extra information in (see glk_gestalt_ext()).
18  *
19  * Returns: an integer, depending on what selector was called.
20  */
21 glui32
22 glk_gestalt(glui32 sel, glui32 val)
23 {
24         return glk_gestalt_ext(sel, val, NULL, 0);
25 }
26
27 /**
28  * glk_gestalt_ext:
29  * @sel: A selector, representing which capability to request information
30  * about.
31  * @val: Extra information, depending on the value of @sel.
32  * @arr: Location of an array to store extra information in, or %NULL.
33  * @arrlen: Length of @arr, or 0 if @arr is %NULL.
34  *
35  * Calls the gestalt system to request information about the capabilities of the
36  * API. The selector @sel tells which capability you are requesting information
37  * about; the other three arguments are additional information, which may or may
38  * not be meaningful. The @arr and @arrlen arguments of glk_gestalt_ext() are
39  * always optional; you may always pass %NULL and 0, if you do not want whatever
40  * information they represent. glk_gestalt() is simply a shortcut for this;
41  * <code>#glk_gestalt(x, y)</code> is exactly the same as 
42  * <code>#glk_gestalt_ext(x, y, %NULL, 0)</code>.
43  *
44  * The critical point is that if the Glk library has never heard of the selector
45  * @sel, it will return 0. It is <emphasis>always</emphasis> safe to call 
46  * <code>#glk_gestalt(x, y)</code> (or <code>#glk_gestalt_ext(x, y, %NULL, 
47  * 0)</code>). Even if you are using an old library, which was compiled before
48  * the given capability was imagined, you can test for the capability by calling
49  * glk_gestalt(); the library will correctly indicate that it does not support
50  * it, by returning 0.
51  *
52  * (It is also safe to call <code>#glk_gestalt_ext(x, y, z, zlen)</code> for an
53  * unknown selector <code>x</code>, where <code>z</code> is not %NULL, as long
54  * as <code>z</code> points at an array of at least <code>zlen</code> elements.
55  * The selector will be careful not to write beyond that point in the array, if
56  * it writes to the array at all.)
57  *
58  * (If a selector does not use the second argument, you should always pass 0; do
59  * not assume that the second argument is simply ignored. This is because the
60  * selector may be extended in the future. You will continue to get the current
61  * behavior if you pass 0 as the second argument, but other values may produce
62  * other behavior.)
63  *
64  * Returns: an integer, depending on what selector was called.
65  */
66 glui32
67 glk_gestalt_ext(glui32 sel, glui32 val, glui32 *arr, glui32 arrlen)
68 {
69         switch(sel)
70         {
71                 /* Version number */
72                 case gestalt_Version:
73                         return (MAJOR_VERSION << 16) + (MINOR_VERSION << 8) + SUB_VERSION;
74                 
75                 /* Which characters can the player type in line input? */
76                 case gestalt_LineInput:
77                         /* Does not accept control chars */
78                         if( val < 32 || (val >= 127 && val <= 159) )
79                                 return 0;
80                         return 1;
81                         
82                 /* Which characters can the player type in char input? */
83                 case gestalt_CharInput:
84                         /* Does not accept control chars or unknown */
85                         if( val < 32 || (val >= 127 && val <= 159) || val == keycode_Unknown )
86                                 return 0;
87                         return 1;
88                 
89                 /* Which characters can we print? */    
90                 case gestalt_CharOutput:
91                         /* All characters are printed as one character, in any case */
92                         if(arr && arrlen > 0)
93                                 *arr = 1;
94                         /* Cannot print control chars except \n */
95                         if( (val < 32 && val != 10) || (val >= 127 && val <= 159) )
96                                 return gestalt_CharOutput_CannotPrint;
97                         /* Can print all other characters */
98                         return gestalt_CharOutput_ExactPrint;
99                 
100                 /* Unicode capabilities present */
101                 case gestalt_Unicode:
102                         return 1;
103
104                 /* Timer capabilities present */
105                 case gestalt_Timer:
106                         return 1;
107
108                 /* Hyperlink capabilities present */
109                 case gestalt_Hyperlinks:
110                         return 1;
111
112                 /* Hyperlinks supported on textbuffers and textgrids */
113                 case gestalt_HyperlinkInput:
114                         return val == wintype_TextBuffer || val == wintype_TextGrid;
115
116                 /* Mouse support present in textgrids */
117                 case gestalt_MouseInput:
118                         return val == wintype_TextGrid;
119
120                 case gestalt_Graphics:
121                         return 1;
122
123                 case gestalt_DrawImage:
124                         return val == wintype_Graphics || val == wintype_TextBuffer;
125
126                 case gestalt_GraphicsTransparency:
127                         return 1;
128
129                 /* Capabilities supported if compiled with GStreamer */
130                 case gestalt_Sound:
131                 case gestalt_SoundVolume:
132                 case gestalt_SoundNotify:
133                 case gestalt_SoundMusic:
134 #ifdef GSTREAMER_SOUND
135                         return 1;
136 #else
137                         return 0;
138 #endif
139                         
140                 /* Unsupported capabilities */
141                 case gestalt_DateTime:
142                 case gestalt_LineInputEcho:
143                 case gestalt_LineTerminatorKey:
144                 case gestalt_LineTerminators:
145                 case gestalt_UnicodeNorm:
146                 /* Selector not supported */    
147                 default:
148                         return 0;
149         }
150 }
151