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