libs/cairomm/cairomm/xlib_surface.h

   1 /* Copyright (C) 2005 The cairomm Development Team
   2  *
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Library General Public
   5  * License as published by the Free Software Foundation; either
   6  * version 2 of the License, or (at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Library General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Library General Public
  14  * License along with this library; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  16  * 02110-1301, USA.
  17  */
  18
  19 #ifndef __CAIROMM_XLIB_SURFACE_H
  20 #define __CAIROMM_XLIB_SURFACE_H
  21
  22 #include <cairomm/surface.h>
  23
  24 // This header is not included by cairomm.h because it requires X headers that
  25 // tend to pollute the namespace with non-prefixed #defines and typedefs.
  26 // You may include it directly if you need to use this API.
  27
  28 #ifdef CAIRO_HAS_XLIB_SURFACE
  29 #include <cairo-xlib.h> //Needed for the X11 "Display" struct (which pollutes the namespace because it has no prefix.)
  30 #endif
  31
  32
  33 namespace Cairo
  34 {
  35
  36 #ifdef CAIRO_HAS_XLIB_SURFACE
  37
  38 /** An XlibSurface provides a way to render to the X Window System using XLib.
  39  * If you want to draw to the screen within an application that uses the X
  40  * Window system, you should use this Surface type.
  41  *
  42  * @note For this surface to be availabe, cairo must have been compiled with
  43  * support for XLib Surfaces
  44  */
  45 class XlibSurface : public Surface
  46 {
  47 public:
  48
  49   /** Create a C++ wrapper for the C instance. This C++ instance should then be
  50    * given to a RefPtr.
  51    *
  52    * @param cobject The C instance.
  53    * @param has_reference whether we already have a reference. Otherwise, the
  54    * constructor will take an extra reference.
  55    */
  56   explicit XlibSurface(cairo_surface_t* cobject, bool has_reference = false);
  57   virtual ~XlibSurface();
  58
  59   /** Creates an Xlib surface that draws to the given drawable. The way that
  60    * colors are represented in the drawable is specified by the provided
  61    * visual.
  62    *
  63    * @note If drawable is a Window, then the function
  64    * cairo_xlib_surface_set_size must be called whenever the size of the window
  65    * changes.
  66    *
  67    * @param dpy an X Display
  68    * @param drawable    an X Drawable, (a Pixmap or a Window)
  69    * @param visual      the visual to use for drawing to drawable. The depth of the visual must match the depth of the drawable. Currently, only TrueColor visuals are fully supported.
  70    * @param width       the current width of drawable.
  71    * @param height      the current height of drawable.
  72    * @return    A RefPtr to the newly created surface
  73    */
  74   static RefPtr<XlibSurface> create(Display* dpy, Drawable drawable, Visual* visual, int width, int height);
  75
  76   /** Creates an Xlib surface that draws to the given bitmap. This will be
  77    * drawn to as a CAIRO_FORMAT_A1 object.
  78    *
  79    * @param dpy an X Display
  80    * @param bitmap      an X Drawable, (a depth-1 Pixmap)
  81    * @param screen      the X Screen associated with bitmap
  82    * @param width       the current width of bitmap.
  83    * @param height      the current height of bitmap.
  84    * @return    A RefPtr to the newly created surface
  85    */
  86   static RefPtr<XlibSurface> create(Display *dpy, Pixmap bitmap, Screen *screen, int width, int height);
  87
  88   /** Informs cairo of the new size of the X Drawable underlying the surface.
  89    * For a surface created for a Window (rather than a Pixmap), this function
  90    * must be called each time the size of the window changes. (For a subwindow,
  91    * you are normally resizing the window yourself, but for a toplevel window,
  92    * it is necessary to listen for ConfigureNotify events.)
  93    *
  94    * A Pixmap can never change size, so it is never necessary to call this
  95    * function on a surface created for a Pixmap.
  96    *
  97    * @param width       the new width of the surface
  98    * @param height      the new height of the surface
  99    */
 100   void set_size(int width, int height);
 101
 102   /** Informs cairo of a new X Drawable underlying the surface. The drawable
 103    * must match the display, screen and format of the existing drawable or the
 104    * application will get X protocol errors and will probably terminate. No
 105    * checks are done by this function to ensure this compatibility.
 106    *
 107    * @param drawable    the new drawable for the surface
 108    * @param width       the width of the new drawable
 109    * @param height      the height of the new drawable
 110    */
 111   void set_drawable(Drawable drawable, int width, int height);
 112
 113   /** gets the Drawable object associated with this surface */
 114   Drawable get_drawable() const;
 115
 116   /** Get the X Display for the underlying X Drawable. */
 117   const Display* get_display() const;
 118   /** Get the X Display for the underlying X Drawable. */
 119   Display* get_display();
 120
 121   /** Get the X Screen for the underlying X Drawable */
 122   Screen* get_screen();
 123   /** Get the X Screen for the underlying X Drawable */
 124   const Screen* get_screen() const;
 125
 126   /** Get the X Visual for the underlying X Drawable */
 127   Visual* get_visual();
 128   /** Get the X Visual for the underlying X Drawable */
 129   const Visual* get_visual() const;
 130
 131   /** Get the number of bits used to represent each pixel value. */
 132   int get_depth() const;
 133
 134   /** Get the height in pixels of the X Drawable underlying the surface */
 135   int get_height() const;
 136
 137   /** Get the width in pixels of the X Drawable underlying the surface */
 138   int get_width() const;
 139
 140 };
 141
 142 #endif // CAIRO_HAS_XLIB_SURFACE
 143
 144 } // namespace Cairo
 145
 146 #endif //__CAIROMM_XLIB_SURFACE_H
 147
 148 // vim: ts=2 sw=2 et