Pileus Git - ~andy/gtk/blob - gdk/gdkcursor.c

   1 /* GDK - The GIMP Drawing Kit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GTK+ Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 #include "config.h"
  26
  27 #include "gdkcursor.h"
  28 #include "gdkcursorprivate.h"
  29 #include "gdkdisplayprivate.h"
  30 #include "gdkintl.h"
  31 #include "gdkinternals.h"
  32
  33
  34 /**
  35  * SECTION:cursors
  36  * @Short_description: Standard and pixmap cursors
  37  * @Title: Cursors
  38  *
  39  * These functions are used to create and destroy cursors.
  40  * There is a number of standard cursors, but it is also
  41  * possible to construct new cursors from pixbufs. There
  42  * may be limitations as to what kinds of cursors can be
  43  * constructed on a given display, see
  44  * gdk_display_supports_cursor_alpha(),
  45  * gdk_display_supports_cursor_color(),
  46  * gdk_display_get_default_cursor_size() and
  47  * gdk_display_get_maximal_cursor_size().
  48  *
  49  * Cursors by themselves are not very interesting, they must be be
  50  * bound to a window for users to see them. This is done with
  51  * gdk_window_set_cursor() or by setting the cursor member of the
  52  * #GdkWindowAttr struct passed to gdk_window_new().
  53  */
  54
  55 /**
  56  * GdkCursor:
  57  *
  58  * The #GdkCursor structure represents a cursor. Its contents are private.
  59  */
  60
  61 enum {
  62   PROP_0,
  63   PROP_CURSOR_TYPE,
  64   PROP_DISPLAY
  65 };
  66
  67 G_DEFINE_ABSTRACT_TYPE (GdkCursor, gdk_cursor, G_TYPE_OBJECT)
  68
  69 static void
  70 gdk_cursor_get_property (GObject    *object,
  71                          guint       prop_id,
  72                          GValue     *value,
  73                          GParamSpec *pspec)
  74 {
  75   GdkCursor *cursor = GDK_CURSOR (object);
  76
  77   switch (prop_id)
  78     {
  79     case PROP_CURSOR_TYPE:
  80       g_value_set_enum (value, cursor->type);
  81       break;
  82     case PROP_DISPLAY:
  83       g_value_set_object (value, cursor->display);
  84       break;
  85     default:
  86       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
  87       break;
  88     }
  89 }
  90
  91 static void
  92 gdk_cursor_set_property (GObject      *object,
  93                          guint         prop_id,
  94                          const GValue *value,
  95                          GParamSpec   *pspec)
  96 {
  97   GdkCursor *cursor = GDK_CURSOR (object);
  98
  99   switch (prop_id)
 100     {
 101     case PROP_CURSOR_TYPE:
 102       cursor->type = g_value_get_enum (value);
 103       break;
 104     case PROP_DISPLAY:
 105       cursor->display = g_value_get_object (value);
 106       /* check that implementations actually provide the display when constructing */
 107       g_assert (cursor->display != NULL);
 108       break;
 109     default:
 110       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 111       break;
 112     }
 113 }
 114
 115 static void
 116 gdk_cursor_class_init (GdkCursorClass *cursor_class)
 117 {
 118   GObjectClass *object_class = G_OBJECT_CLASS (cursor_class);
 119
 120   object_class->get_property = gdk_cursor_get_property;
 121   object_class->set_property = gdk_cursor_set_property;
 122
 123   g_object_class_install_property (object_class,
 124                                    PROP_CURSOR_TYPE,
 125                                    g_param_spec_enum ("cursor-type",
 126                                                       P_("Cursor type"),
 127                                                       P_("Standard cursor type"),
 128                                                       GDK_TYPE_CURSOR_TYPE, GDK_X_CURSOR,
 129                                                       G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 130
 131   g_object_class_install_property (object_class,
 132                                    PROP_DISPLAY,
 133                                    g_param_spec_object ("display",
 134                                                         P_("Display"),
 135                                                         P_("Display of this cursor"),
 136                                                         GDK_TYPE_DISPLAY,
 137                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 138 }
 139
 140 static void
 141 gdk_cursor_init (GdkCursor *cursor)
 142 {
 143 }
 144
 145 /**
 146  * gdk_cursor_ref:
 147  * @cursor: a #GdkCursor
 148  *
 149  * Adds a reference to @cursor.
 150  *
 151  * Return value: (transfer full): Same @cursor that was passed in
 152  *
 153  * Deprecated: 3.0: Use g_object_ref() instead
 154  */
 155 GdkCursor*
 156 gdk_cursor_ref (GdkCursor *cursor)
 157 {
 158   g_return_val_if_fail (cursor != NULL, NULL);
 159
 160   return g_object_ref (cursor);
 161 }
 162
 163 /**
 164  * gdk_cursor_unref:
 165  * @cursor: a #GdkCursor
 166  *
 167  * Removes a reference from @cursor, deallocating the cursor
 168  * if no references remain.
 169  *
 170  * Deprecated: 3.0: Use g_object_unref() instead
 171  */
 172 void
 173 gdk_cursor_unref (GdkCursor *cursor)
 174 {
 175   g_return_if_fail (cursor != NULL);
 176
 177   g_object_unref (cursor);
 178 }
 179
 180 /**
 181  * gdk_cursor_new:
 182  * @cursor_type: cursor to create
 183  *
 184  * Creates a new cursor from the set of builtin cursors for the default display.
 185  * See gdk_cursor_new_for_display().
 186  *
 187  * To make the cursor invisible, use %GDK_BLANK_CURSOR.
 188  *
 189  * Return value: a new #GdkCursor
 190  */
 191 GdkCursor*
 192 gdk_cursor_new (GdkCursorType cursor_type)
 193 {
 194   return gdk_cursor_new_for_display (gdk_display_get_default(), cursor_type);
 195 }
 196
 197 /**
 198  * gdk_cursor_get_cursor_type:
 199  * @cursor:  a #GdkCursor
 200  *
 201  * Returns the cursor type for this cursor.
 202  *
 203  * Return value: a #GdkCursorType
 204  *
 205  * Since: 2.22
 206  **/
 207 GdkCursorType
 208 gdk_cursor_get_cursor_type (GdkCursor *cursor)
 209 {
 210   g_return_val_if_fail (cursor != NULL, GDK_BLANK_CURSOR);
 211
 212   return cursor->type;
 213 }
 214
 215 /**
 216  * gdk_cursor_new_for_display:
 217  * @display: the #GdkDisplay for which the cursor will be created
 218  * @cursor_type: cursor to create
 219  *
 220  * Creates a new cursor from the set of builtin cursors.
 221  * Some useful ones are:
 222  * <itemizedlist>
 223  * <listitem><para>
 224  *  <inlinegraphic format="PNG" fileref="right_ptr.png"></inlinegraphic> #GDK_RIGHT_PTR (right-facing arrow)
 225  * </para></listitem>
 226  * <listitem><para>
 227  *  <inlinegraphic format="PNG" fileref="crosshair.png"></inlinegraphic> #GDK_CROSSHAIR (crosshair)
 228  * </para></listitem>
 229  * <listitem><para>
 230  *  <inlinegraphic format="PNG" fileref="xterm.png"></inlinegraphic> #GDK_XTERM (I-beam)
 231  * </para></listitem>
 232  * <listitem><para>
 233  * <inlinegraphic format="PNG" fileref="watch.png"></inlinegraphic> #GDK_WATCH (busy)
 234  * </para></listitem>
 235  * <listitem><para>
 236  * <inlinegraphic format="PNG" fileref="fleur.png"></inlinegraphic> #GDK_FLEUR (for moving objects)
 237  * </para></listitem>
 238  * <listitem><para>
 239  * <inlinegraphic format="PNG" fileref="hand1.png"></inlinegraphic> #GDK_HAND1 (a right-pointing hand)
 240  * </para></listitem>
 241  * <listitem><para>
 242  * <inlinegraphic format="PNG" fileref="hand2.png"></inlinegraphic> #GDK_HAND2 (a left-pointing hand)
 243  * </para></listitem>
 244  * <listitem><para>
 245  * <inlinegraphic format="PNG" fileref="left_side.png"></inlinegraphic> #GDK_LEFT_SIDE (resize left side)
 246  * </para></listitem>
 247  * <listitem><para>
 248  * <inlinegraphic format="PNG" fileref="right_side.png"></inlinegraphic> #GDK_RIGHT_SIDE (resize right side)
 249  * </para></listitem>
 250  * <listitem><para>
 251  * <inlinegraphic format="PNG" fileref="top_left_corner.png"></inlinegraphic> #GDK_TOP_LEFT_CORNER (resize northwest corner)
 252  * </para></listitem>
 253  * <listitem><para>
 254  * <inlinegraphic format="PNG" fileref="top_right_corner.png"></inlinegraphic> #GDK_TOP_RIGHT_CORNER (resize northeast corner)
 255  * </para></listitem>
 256  * <listitem><para>
 257  * <inlinegraphic format="PNG" fileref="bottom_left_corner.png"></inlinegraphic> #GDK_BOTTOM_LEFT_CORNER (resize southwest corner)
 258  * </para></listitem>
 259  * <listitem><para>
 260  * <inlinegraphic format="PNG" fileref="bottom_right_corner.png"></inlinegraphic> #GDK_BOTTOM_RIGHT_CORNER (resize southeast corner)
 261  * </para></listitem>
 262  * <listitem><para>
 263  * <inlinegraphic format="PNG" fileref="top_side.png"></inlinegraphic> #GDK_TOP_SIDE (resize top side)
 264  * </para></listitem>
 265  * <listitem><para>
 266  * <inlinegraphic format="PNG" fileref="bottom_side.png"></inlinegraphic> #GDK_BOTTOM_SIDE (resize bottom side)
 267  * </para></listitem>
 268  * <listitem><para>
 269  * <inlinegraphic format="PNG" fileref="sb_h_double_arrow.png"></inlinegraphic> #GDK_SB_H_DOUBLE_ARROW (move vertical splitter)
 270  * </para></listitem>
 271  * <listitem><para>
 272  * <inlinegraphic format="PNG" fileref="sb_v_double_arrow.png"></inlinegraphic> #GDK_SB_V_DOUBLE_ARROW (move horizontal splitter)
 273  * </para></listitem>
 274  * <listitem><para>
 275  * #GDK_BLANK_CURSOR (Blank cursor). Since 2.16
 276  * </para></listitem>
 277  * </itemizedlist>
 278  *
 279  * Return value: a new #GdkCursor
 280  *
 281  * Since: 2.2
 282  **/
 283 GdkCursor*
 284 gdk_cursor_new_for_display (GdkDisplay    *display,
 285                             GdkCursorType  cursor_type)
 286 {
 287   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 288
 289   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_type (display, cursor_type);
 290 }
 291
 292 /**
 293  * gdk_cursor_new_from_name:
 294  * @display: the #GdkDisplay for which the cursor will be created
 295  * @name: the name of the cursor
 296  *
 297  * Creates a new cursor by looking up @name in the current cursor
 298  * theme.
 299  *
 300  * Returns: a new #GdkCursor, or %NULL if there is no cursor with
 301  *   the given name
 302  *
 303  * Since: 2.8
 304  */
 305 GdkCursor*
 306 gdk_cursor_new_from_name (GdkDisplay  *display,
 307                           const gchar *name)
 308 {
 309   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 310
 311   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_name (display, name);
 312 }
 313
 314 /**
 315  * gdk_cursor_new_from_pixbuf:
 316  * @display: the #GdkDisplay for which the cursor will be created
 317  * @pixbuf: the #GdkPixbuf containing the cursor image
 318  * @x: the horizontal offset of the 'hotspot' of the cursor.
 319  * @y: the vertical offset of the 'hotspot' of the cursor.
 320  *
 321  * Creates a new cursor from a pixbuf.
 322  *
 323  * Not all GDK backends support RGBA cursors. If they are not
 324  * supported, a monochrome approximation will be displayed.
 325  * The functions gdk_display_supports_cursor_alpha() and
 326  * gdk_display_supports_cursor_color() can be used to determine
 327  * whether RGBA cursors are supported;
 328  * gdk_display_get_default_cursor_size() and
 329  * gdk_display_get_maximal_cursor_size() give information about
 330  * cursor sizes.
 331  *
 332  * If @x or @y are <literal>-1</literal>, the pixbuf must have
 333  * options named "x_hot" and "y_hot", resp., containing
 334  * integer values between %0 and the width resp. height of
 335  * the pixbuf. (Since: 3.0)
 336  *
 337  * On the X backend, support for RGBA cursors requires a
 338  * sufficently new version of the X Render extension.
 339  *
 340  * Returns: a new #GdkCursor.
 341  *
 342  * Since: 2.4
 343  */
 344 GdkCursor *
 345 gdk_cursor_new_from_pixbuf (GdkDisplay *display,
 346                             GdkPixbuf  *pixbuf,
 347                             gint        x,
 348                             gint        y)
 349 {
 350   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 351   g_return_val_if_fail (GDK_IS_PIXBUF (pixbuf), NULL);
 352
 353   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_pixbuf (display, pixbuf, x, y);
 354 }
 355
 356 /**
 357  * gdk_cursor_get_display:
 358  * @cursor: a #GdkCursor.
 359  *
 360  * Returns the display on which the #GdkCursor is defined.
 361  *
 362  * Returns: (transfer none): the #GdkDisplay associated to @cursor
 363  *
 364  * Since: 2.2
 365  */
 366
 367 GdkDisplay *
 368 gdk_cursor_get_display (GdkCursor *cursor)
 369 {
 370   g_return_val_if_fail (GDK_IS_CURSOR (cursor), NULL);
 371
 372   return cursor->display;
 373 }
 374
 375 /**
 376  * gdk_cursor_get_image:
 377  * @cursor: a #GdkCursor
 378  *
 379  * Returns a #GdkPixbuf with the image used to display the cursor.
 380  *
 381  * Note that depending on the capabilities of the windowing system and
 382  * on the cursor, GDK may not be able to obtain the image data. In this
 383  * case, %NULL is returned.
 384  *
 385  * Returns: (transfer full): a #GdkPixbuf representing @cursor, or %NULL
 386  *
 387  * Since: 2.8
 388  */
 389 GdkPixbuf*
 390 gdk_cursor_get_image (GdkCursor *cursor)
 391 {
 392   g_return_val_if_fail (GDK_IS_CURSOR (cursor), NULL);
 393
 394   return GDK_CURSOR_GET_CLASS (cursor)->get_image (cursor);
 395 }