docs/reference/glib/tmpl/macros.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Standard Macros
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 commonly-used macros.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These macros provide a few commonly-used features.
  10 </para>
  11
  12 <!-- ##### SECTION See_Also ##### -->
  13 <para>
  14
  15 </para>
  16
  17 <!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
  18 <para>
  19 The major version number of the GLib library.
  20 </para>
  21
  22
  23
  24 <!-- ##### MACRO GLIB_MINOR_VERSION ##### -->
  25 <para>
  26 The minor version number of the GLib library.
  27 </para>
  28
  29
  30
  31 <!-- ##### MACRO GLIB_MICRO_VERSION ##### -->
  32 <para>
  33 The micro version number of the GLib library.
  34 </para>
  35
  36
  37
  38 <!-- ##### MACRO G_OS_WIN32 ##### -->
  39 <para>
  40 This macro is defined only on Windows. So you can bracket
  41 Windows-specific code in "&num;ifdef G_OS_WIN32".
  42 </para>
  43
  44
  45
  46 <!-- ##### MACRO G_OS_BEOS ##### -->
  47 <para>
  48 This macro is defined only on BeOS. So you can bracket
  49 BeOS-specific code in "&num;ifdef G_OS_BEOS".
  50 </para>
  51
  52
  53
  54 <!-- ##### MACRO G_OS_UNIX ##### -->
  55 <para>
  56 This macro is defined only on UNIX. So you can bracket
  57 UNIX-specific code in "&num;ifdef G_OS_UNIX".
  58 </para>
  59
  60
  61
  62 <!-- ##### MACRO GLIB_CHECK_VERSION ##### -->
  63 <para>
  64 Checks the version of the GLib library.
  65 It returns %TRUE if the GLib library is the same or newer than the given
  66 version.
  67
  68 <example>
  69 <title>Checking the version of the GLib library.</title>
  70 <programlisting>
  71   if (!GLIB_CHECK_VERSION (1, 2, 0))
  72     g_error ("GLib version 1.2.0 or above is needed");
  73 </programlisting>
  74 </example>
  75 </para>
  76
  77 @major: the major version number.
  78 @minor: the minor version number.
  79 @micro: the micro version number.
  80
  81
  82 <!-- ##### MACRO G_DIR_SEPARATOR ##### -->
  83 <para>
  84 The directory separator character.
  85 This is '/' on UNIX machines and '\' under Windows.
  86 </para>
  87
  88
  89
  90 <!-- ##### MACRO G_DIR_SEPARATOR_S ##### -->
  91 <para>
  92 The directory separator as a string.
  93 This is "/" on UNIX machines and "\" under Windows.
  94 </para>
  95
  96
  97
  98 <!-- ##### MACRO G_SEARCHPATH_SEPARATOR ##### -->
  99 <para>
 100 The search path separator character.
 101 This is ':' on UNIX machines and ';' under Windows.
 102 </para>
 103
 104
 105
 106 <!-- ##### MACRO G_SEARCHPATH_SEPARATOR_S ##### -->
 107 <para>
 108 The search path separator as a string.
 109 This is ":" on UNIX machines and ";" under Windows.
 110 </para>
 111
 112
 113
 114 <!-- ##### MACRO TRUE ##### -->
 115 <para>
 116 Defines the %TRUE value for the #gboolean type.
 117 </para>
 118
 119
 120
 121 <!-- ##### MACRO FALSE ##### -->
 122 <para>
 123 Defines the %FALSE value for the #gboolean type.
 124 </para>
 125
 126
 127
 128 <!-- ##### MACRO NULL ##### -->
 129 <para>
 130 Defines the standard %NULL pointer.
 131 </para>
 132
 133
 134
 135 <!-- ##### MACRO MIN ##### -->
 136 <para>
 137 Calculates the minimum of @a and @b.
 138 </para>
 139
 140 @a: a numeric value.
 141 @b: a numeric value.
 142 @Returns: the minimum of @a and @b.
 143
 144
 145 <!-- ##### MACRO MAX ##### -->
 146 <para>
 147 Calculates the maximum of @a and @b.
 148 </para>
 149
 150 @a: a numeric value.
 151 @b: a numeric value.
 152 @Returns: the maximum of @a and @b.
 153
 154
 155 <!-- ##### MACRO ABS ##### -->
 156 <para>
 157 Calculates the absolute value of @a.
 158 The absolute value is simply the number with any negative sign taken away.
 159 </para>
 160 <para>
 161 For example,
 162 <itemizedlist>
 163 <listitem><para>
 164 ABS(-10) is 10.
 165 </para></listitem>
 166 <listitem><para>
 167 ABS(10) is also 10.
 168 </para></listitem>
 169 </itemizedlist>
 170 </para>
 171
 172 @a: a numeric value.
 173 @Returns: the absolute value of @a.
 174
 175
 176 <!-- ##### MACRO CLAMP ##### -->
 177 <para>
 178 Ensures that @x is between the limits set by @low and @high.
 179 </para>
 180 <para>
 181 For example,
 182 <itemizedlist>
 183 <listitem><para>
 184 CLAMP(5, 10, 15) is 10.
 185 </para></listitem>
 186 <listitem><para>
 187 CLAMP(15, 5, 10) is 10.
 188 </para></listitem>
 189 <listitem><para>
 190 CLAMP(20, 15, 25) is 20.
 191 </para></listitem>
 192 </itemizedlist>
 193 </para>
 194
 195 @x: the value to clamp.
 196 @low: the minimum value allowed.
 197 @high: the maximum value allowed.
 198 @Returns: the value of @x clamped to the range between @low and @high.
 199
 200
 201 <!-- ##### MACRO G_STRUCT_MEMBER ##### -->
 202 <para>
 203 Returns a member of a structure at a given offset, using the given type.
 204 </para>
 205
 206 @member_type: the type of the struct field.
 207 @struct_p: a pointer to a struct.
 208 @struct_offset: the offset of the field from the start of the struct, in bytes.
 209 @Returns: the struct member.
 210
 211
 212 <!-- ##### MACRO G_STRUCT_MEMBER_P ##### -->
 213 <para>
 214 Returns an untyped pointer to a given offset of a struct.
 215 </para>
 216
 217 @struct_p: a pointer to a struct.
 218 @struct_offset: the offset from the start of the struct, in bytes.
 219 @Returns: an untyped pointer to @struct_p plus @struct_offset bytes.
 220
 221
 222 <!-- ##### MACRO G_STRUCT_OFFSET ##### -->
 223 <para>
 224 Returns the offset, in bytes, of a member of a struct.
 225 </para>
 226
 227 @struct_type: a structure type, e.g. <structname>GtkWidget</structname>.
 228 @member: a field in the structure, e.g. <structfield>window</structfield>.
 229 @Returns: the offset of @member from the start of @struct_type.
 230
 231
 232 <!-- ##### MACRO G_MEM_ALIGN ##### -->
 233 <para>
 234 Indicates the number of bytes to which memory will be aligned on the
 235 current platform.
 236 </para>
 237
 238
 239
 240 <!-- ##### MACRO G_CONST_RETURN ##### -->
 241 <para>
 242 If %G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing.
 243 By default, the macro expands to <literal>const</literal>. The macro
 244 should be used in place of <literal>const</literal> for functions that
 245 return a value that should not be modified. The purpose of this macro is
 246 to allow us to turn on <literal>const</literal> for returned constant
 247 strings by default, while allowing programmers who find that annoying to
 248 turn it off. This macro should only be used for return values and for
 249 <emphasis>out</emphasis> parameters, it doesn't make sense for
 250 <emphasis>in</emphasis> parameters.
 251 </para>
 252
 253
 254