Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/cursors.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Cursors
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 standard and pixmap cursors.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9
  10 </para>
  11
  12 <!-- ##### SECTION See_Also ##### -->
  13 <para>
  14
  15 </para>
  16
  17 <!-- ##### STRUCT GdkCursor ##### -->
  18 <para>
  19 A <type>GdkCursor</type> structure represents a cursor.
  20 </para>
  21
  22 @type:
  23 @ref_count:
  24
  25 <!-- ##### ENUM GdkCursorType ##### -->
  26 <para>
  27 The standard cursors available.
  28 </para>
  29
  30 @GDK_X_CURSOR: <inlinegraphic format="PNG" fileref="X_cursor.png"></inlinegraphic>
  31 @GDK_ARROW: <inlinegraphic format="PNG" fileref="arrow.png"></inlinegraphic>
  32 @GDK_BASED_ARROW_DOWN: <inlinegraphic format="PNG" fileref="based_arrow_down.png"></inlinegraphic>
  33 @GDK_BASED_ARROW_UP: <inlinegraphic format="PNG" fileref="based_arrow_up.png"></inlinegraphic>
  34 @GDK_BOAT: <inlinegraphic format="PNG" fileref="boat.png"></inlinegraphic>
  35 @GDK_BOGOSITY: <inlinegraphic format="PNG" fileref="bogosity.png"></inlinegraphic>
  36 @GDK_BOTTOM_LEFT_CORNER: <inlinegraphic format="PNG" fileref="bottom_left_corner.png"></inlinegraphic>
  37 @GDK_BOTTOM_RIGHT_CORNER: <inlinegraphic format="PNG" fileref="bottom_right_corner.png"></inlinegraphic>
  38 @GDK_BOTTOM_SIDE: <inlinegraphic format="PNG" fileref="bottom_side.png"></inlinegraphic>
  39 @GDK_BOTTOM_TEE: <inlinegraphic format="PNG" fileref="bottom_tee.png"></inlinegraphic>
  40 @GDK_BOX_SPIRAL: <inlinegraphic format="PNG" fileref="box_spiral.png"></inlinegraphic>
  41 @GDK_CENTER_PTR: <inlinegraphic format="PNG" fileref="center_ptr.png"></inlinegraphic>
  42 @GDK_CIRCLE: <inlinegraphic format="PNG" fileref="circle.png"></inlinegraphic>
  43 @GDK_CLOCK: <inlinegraphic format="PNG" fileref="clock.png"></inlinegraphic>
  44 @GDK_COFFEE_MUG: <inlinegraphic format="PNG" fileref="coffee_mug.png"></inlinegraphic>
  45 @GDK_CROSS: <inlinegraphic format="PNG" fileref="cross.png"></inlinegraphic>
  46 @GDK_CROSS_REVERSE: <inlinegraphic format="PNG" fileref="cross_reverse.png"></inlinegraphic>
  47 @GDK_CROSSHAIR: <inlinegraphic format="PNG" fileref="crosshair.png"></inlinegraphic>
  48 @GDK_DIAMOND_CROSS: <inlinegraphic format="PNG" fileref="diamond_cross.png"></inlinegraphic>
  49 @GDK_DOT: <inlinegraphic format="PNG" fileref="dot.png"></inlinegraphic>
  50 @GDK_DOTBOX: <inlinegraphic format="PNG" fileref="dotbox.png"></inlinegraphic>
  51 @GDK_DOUBLE_ARROW: <inlinegraphic format="PNG" fileref="double_arrow.png"></inlinegraphic>
  52 @GDK_DRAFT_LARGE: <inlinegraphic format="PNG" fileref="draft_large.png"></inlinegraphic>
  53 @GDK_DRAFT_SMALL: <inlinegraphic format="PNG" fileref="draft_small.png"></inlinegraphic>
  54 @GDK_DRAPED_BOX: <inlinegraphic format="PNG" fileref="draped_box.png"></inlinegraphic>
  55 @GDK_EXCHANGE: <inlinegraphic format="PNG" fileref="exchange.png"></inlinegraphic>
  56 @GDK_FLEUR: <inlinegraphic format="PNG" fileref="fleur.png"></inlinegraphic>
  57 @GDK_GOBBLER: <inlinegraphic format="PNG" fileref="gobbler.png"></inlinegraphic>
  58 @GDK_GUMBY: <inlinegraphic format="PNG" fileref="gumby.png"></inlinegraphic>
  59 @GDK_HAND1: <inlinegraphic format="PNG" fileref="hand1.png"></inlinegraphic>
  60 @GDK_HAND2: <inlinegraphic format="PNG" fileref="hand2.png"></inlinegraphic>
  61 @GDK_HEART: <inlinegraphic format="PNG" fileref="heart.png"></inlinegraphic>
  62 @GDK_ICON: <inlinegraphic format="PNG" fileref="icon.png"></inlinegraphic>
  63 @GDK_IRON_CROSS: <inlinegraphic format="PNG" fileref="iron_cross.png"></inlinegraphic>
  64 @GDK_LEFT_PTR: <inlinegraphic format="PNG" fileref="left_ptr.png"></inlinegraphic>
  65 @GDK_LEFT_SIDE: <inlinegraphic format="PNG" fileref="left_side.png"></inlinegraphic>
  66 @GDK_LEFT_TEE: <inlinegraphic format="PNG" fileref="left_tee.png"></inlinegraphic>
  67 @GDK_LEFTBUTTON: <inlinegraphic format="PNG" fileref="leftbutton.png"></inlinegraphic>
  68 @GDK_LL_ANGLE: <inlinegraphic format="PNG" fileref="ll_angle.png"></inlinegraphic>
  69 @GDK_LR_ANGLE: <inlinegraphic format="PNG" fileref="lr_angle.png"></inlinegraphic>
  70 @GDK_MAN: <inlinegraphic format="PNG" fileref="man.png"></inlinegraphic>
  71 @GDK_MIDDLEBUTTON: <inlinegraphic format="PNG" fileref="middlebutton.png"></inlinegraphic>
  72 @GDK_MOUSE: <inlinegraphic format="PNG" fileref="mouse.png"></inlinegraphic>
  73 @GDK_PENCIL: <inlinegraphic format="PNG" fileref="pencil.png"></inlinegraphic>
  74 @GDK_PIRATE: <inlinegraphic format="PNG" fileref="pirate.png"></inlinegraphic>
  75 @GDK_PLUS: <inlinegraphic format="PNG" fileref="plus.png"></inlinegraphic>
  76 @GDK_QUESTION_ARROW: <inlinegraphic format="PNG" fileref="question_arrow.png"></inlinegraphic>
  77 @GDK_RIGHT_PTR: <inlinegraphic format="PNG" fileref="right_ptr.png"></inlinegraphic>
  78 @GDK_RIGHT_SIDE: <inlinegraphic format="PNG" fileref="right_side.png"></inlinegraphic>
  79 @GDK_RIGHT_TEE: <inlinegraphic format="PNG" fileref="right_tee.png"></inlinegraphic>
  80 @GDK_RIGHTBUTTON: <inlinegraphic format="PNG" fileref="rightbutton.png"></inlinegraphic>
  81 @GDK_RTL_LOGO: <inlinegraphic format="PNG" fileref="rtl_logo.png"></inlinegraphic>
  82 @GDK_SAILBOAT: <inlinegraphic format="PNG" fileref="sailboat.png"></inlinegraphic>
  83 @GDK_SB_DOWN_ARROW: <inlinegraphic format="PNG" fileref="sb_down_arrow.png"></inlinegraphic>
  84 @GDK_SB_H_DOUBLE_ARROW: <inlinegraphic format="PNG" fileref="sb_h_double_arrow.png"></inlinegraphic>
  85 @GDK_SB_LEFT_ARROW: <inlinegraphic format="PNG" fileref="sb_left_arrow.png"></inlinegraphic>
  86 @GDK_SB_RIGHT_ARROW: <inlinegraphic format="PNG" fileref="sb_right_arrow.png"></inlinegraphic>
  87 @GDK_SB_UP_ARROW: <inlinegraphic format="PNG" fileref="sb_up_arrow.png"></inlinegraphic>
  88 @GDK_SB_V_DOUBLE_ARROW: <inlinegraphic format="PNG" fileref="sb_v_double_arrow.png"></inlinegraphic>
  89 @GDK_SHUTTLE: <inlinegraphic format="PNG" fileref="shuttle.png"></inlinegraphic>
  90 @GDK_SIZING: <inlinegraphic format="PNG" fileref="sizing.png"></inlinegraphic>
  91 @GDK_SPIDER: <inlinegraphic format="PNG" fileref="spider.png"></inlinegraphic>
  92 @GDK_SPRAYCAN: <inlinegraphic format="PNG" fileref="spraycan.png"></inlinegraphic>
  93 @GDK_STAR: <inlinegraphic format="PNG" fileref="star.png"></inlinegraphic>
  94 @GDK_TARGET: <inlinegraphic format="PNG" fileref="target.png"></inlinegraphic>
  95 @GDK_TCROSS: <inlinegraphic format="PNG" fileref="tcross.png"></inlinegraphic>
  96 @GDK_TOP_LEFT_ARROW: <inlinegraphic format="PNG" fileref="top_left_arrow.png"></inlinegraphic>
  97 @GDK_TOP_LEFT_CORNER: <inlinegraphic format="PNG" fileref="top_left_corner.png"></inlinegraphic>
  98 @GDK_TOP_RIGHT_CORNER: <inlinegraphic format="PNG" fileref="top_right_corner.png"></inlinegraphic>
  99 @GDK_TOP_SIDE: <inlinegraphic format="PNG" fileref="top_side.png"></inlinegraphic>
 100 @GDK_TOP_TEE: <inlinegraphic format="PNG" fileref="top_tee.png"></inlinegraphic>
 101 @GDK_TREK: <inlinegraphic format="PNG" fileref="trek.png"></inlinegraphic>
 102 @GDK_UL_ANGLE: <inlinegraphic format="PNG" fileref="ul_angle.png"></inlinegraphic>
 103 @GDK_UMBRELLA: <inlinegraphic format="PNG" fileref="umbrella.png"></inlinegraphic>
 104 @GDK_UR_ANGLE: <inlinegraphic format="PNG" fileref="ur_angle.png"></inlinegraphic>
 105 @GDK_WATCH: <inlinegraphic format="PNG" fileref="watch.png"></inlinegraphic>
 106 @GDK_XTERM: <inlinegraphic format="PNG" fileref="xterm.png"></inlinegraphic>
 107 @GDK_LAST_CURSOR:
 108 @GDK_CURSOR_IS_PIXMAP: type of cursors constructed with
 109     gdk_cursor_new_from_pixmap().
 110
 111 <!-- ##### FUNCTION gdk_cursor_new ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @cursor_type:
 117 @Returns:
 118
 119
 120 <!-- ##### FUNCTION gdk_cursor_new_from_pixmap ##### -->
 121 <para>
 122 Creates a new cursor from a given pixmap and mask. Both the pixmap and mask
 123 must have a depth of 1 (i.e. each pixel has only 2 values - on or off).
 124 The standard cursor size is 16 by 16 pixels. You can create a bitmap
 125 from inline data as in the below example.
 126 </para>
 127 <example><title>Creating a custom cursor.</title>
 128 <programlisting>
 129 /* This data is in X bitmap format, and can be created with the 'bitmap'
 130    utility. */
 131 &hash;define cursor1_width 16
 132 &hash;define cursor1_height 16
 133 static unsigned char cursor1_bits[] = {
 134    0x80, 0x01, 0x40, 0x02, 0x20, 0x04, 0x10, 0x08, 0x08, 0x10, 0x04, 0x20,
 135    0x82, 0x41, 0x41, 0x82, 0x41, 0x82, 0x82, 0x41, 0x04, 0x20, 0x08, 0x10,
 136    0x10, 0x08, 0x20, 0x04, 0x40, 0x02, 0x80, 0x01};
 137
 138 static unsigned char cursor1mask_bits[] = {
 139    0x80, 0x01, 0xc0, 0x03, 0x60, 0x06, 0x30, 0x0c, 0x18, 0x18, 0x8c, 0x31,
 140    0xc6, 0x63, 0x63, 0xc6, 0x63, 0xc6, 0xc6, 0x63, 0x8c, 0x31, 0x18, 0x18,
 141    0x30, 0x0c, 0x60, 0x06, 0xc0, 0x03, 0x80, 0x01};
 142
 143
 144   GdkCursor *cursor;
 145   GdkPixmap *source, *mask;
 146   GdkColor fg = { 0, 65535, 0, 0 }; /* Red. */
 147   GdkColor bg = { 0, 0, 0, 65535 }; /* Blue. */
 148
 149
 150   source = gdk_bitmap_create_from_data (NULL, cursor1_bits,
 151                                         cursor1_width, cursor1_height);
 152   mask = gdk_bitmap_create_from_data (NULL, cursor1mask_bits,
 153                                       cursor1_width, cursor1_height);
 154   cursor = gdk_cursor_new_from_pixmap (source, mask, &amp;fg, &amp;bg, 8, 8);
 155   gdk_pixmap_unref (source);
 156   gdk_pixmap_unref (mask);
 157
 158
 159   gdk_window_set_cursor (widget->window, cursor);
 160 </programlisting>
 161 </example>
 162
 163 @source: the pixmap specifying the cursor.
 164 @mask: the pixmap specifying the mask, which must be the same size as @source.
 165 @fg: the foreground color, used for the bits in the source which are 1.
 166 The color does not have to be allocated first.
 167 @bg: the background color, used for the bits in the source which are 0.
 168 The color does not have to be allocated first.
 169 @x: the horizontal offset of the 'hotspot' of the cursor.
 170 @y: the vertical offset of the 'hotspot' of the cursor.
 171 @Returns: a new #GdkCursor.
 172
 173
 174 <!-- ##### FUNCTION gdk_cursor_new_for_screen ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @screen:
 180 @cursor_type:
 181 @Returns:
 182
 183
 184 <!-- ##### FUNCTION gdk_cursor_get_screen ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @cursor:
 190 @Returns:
 191
 192
 193 <!-- ##### FUNCTION gdk_cursor_ref ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @cursor:
 199 @Returns:
 200
 201
 202 <!-- ##### FUNCTION gdk_cursor_unref ##### -->
 203 <para>
 204
 205 </para>
 206
 207 @cursor:
 208
 209
 210 <!-- ##### MACRO gdk_cursor_destroy ##### -->
 211 <para>
 212 Destroys a cursor, freeing any resources allocated for it.
 213 </para>
 214
 215 <!-- # Unused Parameters # -->
 216 @cursor: a #GdkCursor.
 217
 218