// -*- c++ -*-
// Generated by gtkmmproc -- DO NOT MODIFY!
#ifndef _GDKMM_DISPLAY_H
#define _GDKMM_DISPLAY_H


#include <glibmm.h>

/* $Id: display.hg,v 1.22 2006/04/12 11:11:24 murrayc Exp $ */

/* display.h
 *
 * Copyright (C) 1998-2002 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <gdkmm/screen.h>
#include <gdkmm/device.h>
#include <gdkmm/devicemanager.h>
#include <gdkmm/types.h> //For ModifierType


#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef struct _GdkDisplay GdkDisplay;
typedef struct _GdkDisplayClass GdkDisplayClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */


namespace Gdk
{ class Display_Class; } // namespace Gdk
namespace Gdk
{


class Drawable;
class DeviceManager;

 /** Gdk::Display object's purpose is two fold:
 *   To grab/ungrab keyboard focus and mouse pointer
 *   To manage and provide information about the Gdk::Screen(s) available for this Gdk::Display
 *
 * Gdk::Display objects are the GDK representation of the X Display which can be described as a workstation consisting
 * of a keyboard a pointing device (such as a mouse) and one or more screens. It is used to open and keep track of
 * various Gdk::Screen objects currently instantiated by the application. It is also used to grab and release the keyboard
 * and the mouse pointer.
 */

class Display : public Glib::Object
{
  
#ifndef DOXYGEN_SHOULD_SKIP_THIS

public:
  typedef Display CppObjectType;
  typedef Display_Class CppClassType;
  typedef GdkDisplay BaseObjectType;
  typedef GdkDisplayClass BaseClassType;

private:  friend class Display_Class;
  static CppClassType display_class_;

private:
  // noncopyable
  Display(const Display&);
  Display& operator=(const Display&);

protected:
  explicit Display(const Glib::ConstructParams& construct_params);
  explicit Display(GdkDisplay* castitem);

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

public:
  virtual ~Display();

#ifndef DOXYGEN_SHOULD_SKIP_THIS
  static GType get_type()      G_GNUC_CONST;


  static GType get_base_type() G_GNUC_CONST;
#endif

  ///Provides access to the underlying C GObject.
  GdkDisplay*       gobj()       { return reinterpret_cast<GdkDisplay*>(gobject_); }

  ///Provides access to the underlying C GObject.
  const GdkDisplay* gobj() const { return reinterpret_cast<GdkDisplay*>(gobject_); }

  ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
  GdkDisplay* gobj_copy();

private:

protected:
  Display();

public:
  
  /** Opens a display.
   * 
   * @newin{2,2}
   * @param display_name The name of the display to open.
   * @return A Gdk::Display, or <tt>0</tt> if the display
   * could not be opened.
   */
  static Glib::RefPtr<Display> open(const Glib::ustring& display_name);

  
  /** Gets the name of the display.
   * 
   * @newin{2,2}
   * @return A string representing the display name. This string is owned
   * by GDK and should not be modified or freed.
   */
  Glib::ustring get_name() const;

  
  /** Gets the number of screen managed by the @a display.
   * 
   * @newin{2,2}
   * @return Number of screens.
   */
  int get_n_screens() const;
  
  /** Returns a screen object for one of the screens of the display.
   * 
   * @newin{2,2}
   * @param screen_num The screen number.
   * @return The Gdk::Screen object.
   */
  Glib::RefPtr<Screen> get_screen(int screen_num);
  
  /** Returns a screen object for one of the screens of the display.
   * 
   * @newin{2,2}
   * @param screen_num The screen number.
   * @return The Gdk::Screen object.
   */
  Glib::RefPtr<const Screen> get_screen(int screen_num) const;

  
  /** Get the default Gdk::Screen for @a display.
   * 
   * @newin{2,2}
   * @return The default Gdk::Screen object for @a display.
   */
  Glib::RefPtr<Screen> get_default_screen();
  
  /** Get the default Gdk::Screen for @a display.
   * 
   * @newin{2,2}
   * @return The default Gdk::Screen object for @a display.
   */
  Glib::RefPtr<const Screen> get_default_screen() const;

  
  /** Release any pointer grab.
   * 
   * @newin{2,2}
   * @param timestamp A timestap (e.g. GDK_CURRENT_TIME).
   */
  void pointer_ungrab(guint32 timestamp);
  
  /** Release any keyboard grab
   * 
   * @newin{2,2}
   * @param timestamp A timestap (e.g Gdk::CURRENT_TIME).
   */
  void keyboard_ungrab(guint32 timestamp);
  
  /** Test if the pointer is grabbed.
   * 
   * @newin{2,2}
   * @return <tt>true</tt> if an active X pointer grab is in effect.
   */
  bool pointer_is_grabbed() const;
  
  bool device_is_grabbed(const Glib::RefPtr<Device>& device) const;
  
  /** Emits a short beep on @a display
   * 
   * @newin{2,2}
   */
  void beep();
  
  /** Flushes any requests queued for the windowing system and waits until all
   * requests have been handled. This is often used for making sure that the
   * display is synchronized with the current state of the program. Calling
   * sync() before gdk_error_trap_pop() makes sure that any errors
   * generated from earlier requests are handled before the error trap is 
   * removed.
   * 
   * This is most useful for X11. On windowing systems where requests are
   * handled synchronously, this function will do nothing.
   * 
   * @newin{2,2}
   */
  void sync();
  
  /** Closes the connection to the windowing system for the given display,
   * and cleans up associated resources.
   * 
   * @newin{2,2}
   */
  void	close();
  
  bool is_closed() const;


   //deprecated

  //TODO: Use C++ Gdk::Event:
  //TODO: get_event() might remove the event - if so, then there should not be a const version:
  
  /** Gets the next Gdk::Event to be processed for @a display, fetching events from the
   * windowing system if necessary.
   * 
   * @newin{2,2}
   * @return The next Gdk::Event to be processed, or <tt>0</tt> if no events
   * are pending. The returned Gdk::Event should be freed with Gdk::Event::free().
   */
  GdkEvent* get_event();
  
  /** Gets the next Gdk::Event to be processed for @a display, fetching events from the
   * windowing system if necessary.
   * 
   * @newin{2,2}
   * @return The next Gdk::Event to be processed, or <tt>0</tt> if no events
   * are pending. The returned Gdk::Event should be freed with Gdk::Event::free().
   */
  const GdkEvent* get_event() const;

  
  /** Gets a copy of the first Gdk::Event in the @a display's event queue, without
   * removing the event from the queue.  (Note that this function will
   * not get more events from the windowing system.  It only checks the events
   * that have already been moved to the GDK event queue.)
   * 
   * @newin{2,2}
   * @return A copy of the first Gdk::Event on the event queue, or <tt>0</tt> 
   * if no events are in the queue. The returned Gdk::Event should be freed with
   * Gdk::Event::free().
   */
  GdkEvent* peek_event();
  
  /** Gets a copy of the first Gdk::Event in the @a display's event queue, without
   * removing the event from the queue.  (Note that this function will
   * not get more events from the windowing system.  It only checks the events
   * that have already been moved to the GDK event queue.)
   * 
   * @newin{2,2}
   * @return A copy of the first Gdk::Event on the event queue, or <tt>0</tt> 
   * if no events are in the queue. The returned Gdk::Event should be freed with
   * Gdk::Event::free().
   */
  GdkEvent* peek_event() const;
  
  /** Appends a copy of the given event onto the front of the event
   * queue for @a display.
   * 
   * @newin{2,2}
   * @param event A Gdk::Event.
   */
  void put_event(GdkEvent* event);

  //TODO: Use a slot here, though this is probably never used anyway:
  //Find out whether we can use a string representation for the atom - look for examples of this function's use.
  
  /** Adds a filter to be called when X ClientMessage events are received.
   * See Gdk::Window::add_filter() if you are interested in filtering other
   * types of events.
   * 
   * @newin{2,2}
   * @param message_type The type of ClientMessage events to receive.
   * This will be checked against the @a message_type field 
   * of the XClientMessage event struct.
   * @param func The function to call to process the event.
   * @param data User data to pass to @a func.
   */
  void add_client_message_filter(Glib::ustring& message_type, GdkFilterFunc func, gpointer data);

  
  /** Sets the double click time (two clicks within this time interval
   * count as a double click and result in a Gdk::2BUTTON_PRESS event).
   * Applications should <emphasis>not</emphasis> set this, it is a global 
   * user-configured setting.
   * 
   * @newin{2,2}
   * @param msec Double click time in milliseconds (thousandths of a second).
   */
  void set_double_click_time(guint msec);
  
  /** Sets the double click distance (two clicks within this distance
   * count as a double click and result in a Gdk::2BUTTON_PRESS event).
   * See also set_double_click_time().
   * Applications should <emphasis>not</emphasis> set this, it is a global 
   * user-configured setting.
   * 
   * @newin{2,4}
   * @param distance Distance in pixels.
   */
  void set_double_click_distance(guint distance);


  /** Gets the default Gdk::Display. This is a convenience
   * function for
   * <literal>gdk_display_manager_get_default_display (manager_get())</literal>.
   * 
   * @newin{2,2}
   * @return A Gdk::Display, or <tt>0</tt> if there is no default
   * display.
   */
  static Glib::RefPtr<Display> get_default();

  /** Gets the current location of the pointer and the current modifier
   * mask for a given display.
   *
   * @param screen location to store the screen that the cursor is on.
   * @param x location to store root window X coordinate of pointer.
   * @param y location to store root window Y coordinate of pointer.
   * @param mask location to store current modifier mask.
   *
   **/
  void get_pointer(Glib::RefPtr<Screen>& screen, int& x, int& y, ModifierType& mask);

   //deprecated

  // In fact, any one of these gdk_display_get_pointer() args can be NULL, but we don't need so many overloads.
  /**
   * Gets the current location of the pointer and the current modifier
   * mask for a given display.
   *
   * @param x location to store root window X coordinate of pointer.
   * @param y location to store root window Y coordinate of pointer.
   * @param mask location to store current modifier mask.
   *
   **/
  void get_pointer(int& x, int& y, ModifierType& mask);
  

  /** Obtains the window underneath the mouse pointer, returning the location
   * of the pointer in that window in @a win_x, @a win_y for @a screen. Returns <tt>0</tt>
   * if the window under the mouse pointer is not known to GDK (for example, 
   * belongs to another application).
   * 
   * @newin{2,2}
   * @param win_x Return location for x coordinate of the pointer location relative
   * to the window origin, or <tt>0</tt>.
   * @param win_y Return location for y coordinate of the pointer location relative
   *  &    to the window origin, or <tt>0</tt>.
   * @return The window under the mouse pointer, or <tt>0</tt>.
   */
  Glib::RefPtr<Window> get_window_at_pointer(int& win_x, int& win_y);
  
  /** Obtains the window underneath the mouse pointer, returning the location
   * of the pointer in that window in @a win_x, @a win_y for @a screen. Returns <tt>0</tt>
   * if the window under the mouse pointer is not known to GDK (for example, 
   * belongs to another application).
   * 
   * @newin{2,2}
   * @param win_x Return location for x coordinate of the pointer location relative
   * to the window origin, or <tt>0</tt>.
   * @param win_y Return location for y coordinate of the pointer location relative
   *  &    to the window origin, or <tt>0</tt>.
   * @return The window under the mouse pointer, or <tt>0</tt>.
   */
  Glib::RefPtr<const Window> get_window_at_pointer(int& win_x, int& win_y) const;

  /** Obtains the window underneath the mouse pointer. Returns a null RefPtr if the window
   * under the mouse pointer is not known to GDK (for example, belongs to
   * another application).
   * @result The window underneath the mouse pointer.
   */
  Glib::RefPtr<Window> get_window_at_pointer();

  /** Obtains the window underneath the mouse pointer. Returns a null RefPtr if the window
   * under the mouse pointer is not known to GDK (for example, belongs to
   * another application).
   * @result The window underneath the mouse pointer.
   */
  Glib::RefPtr<const Window> get_window_at_pointer() const;

  //TODO: Documentation
  void get_device_state(const Glib::RefPtr<Device>& device, Glib::RefPtr<Screen>& screen, int& x, int& y, ModifierType& mask);
  //TODO: Documentation
  void get_device_state(const Glib::RefPtr<Device>& device, int& x, int& y, ModifierType& mask);
  

  Glib::RefPtr<const Window> get_window_at_device_position(const Glib::RefPtr<Device>& device, int& win_x, int& win_y);
  
  void warp_device(const Glib::RefPtr<Device>& device, const Glib::RefPtr<Screen>& screen, int x, int y);


  /** Warps the pointer of @a display to the point @a x, @a y on 
   * the screen @a screen, unless the pointer is confined
   * to a window by a grab, in which case it will be moved
   * as far as allowed by the grab. Warping the pointer 
   * creates events as if the user had moved the mouse 
   * instantaneously to the destination.
   * 
   * Note that the pointer should normally be under the
   * control of the user. This function was added to cover
   * some rare use cases like keyboard navigation support
   * for the color picker in the Gtk::ColorSelectionDialog.
   * 
   * @newin{2,8}
   * @param screen The screen of @a display to warp the pointer to.
   * @param x The x coordinate of the destination.
   * @param y The y coordinate of the destination.
   */
  void warp_pointer(const Glib::RefPtr<Screen>& screen, int x, int y);

  //TODO: Wrap this array parameter as a vector?
  
  /** This function allows for hooking into the operation
   * of getting the current location of the pointer on a particular
   * display. This is only useful for such low-level tools as an
   * event recorder. Applications should never have any
   * reason to use this facility.
   * 
   * @newin{2,2}
   * @param new_hooks A table of pointers to functions for getting
   * quantities related to the current pointer position.
   * @return The previous pointer hook table.
   */
  GdkDisplayPointerHooks* set_pointer_hooks(const GdkDisplayPointerHooks* new_hooks);
  //TODO: Documentation.
  GdkDisplayPointerHooks* unset_pointer_hooks();

  //TODO: Wrap this array parameter as a vector?
  
  GdkDisplayDeviceHooks* set_device_hooks(const GdkDisplayDeviceHooks *new_hooks);
  //TODO: Documentation.
  GdkDisplayDeviceHooks* unset_device_hooks();

  
  /** Opens the default display specified by command line arguments or
   * environment variables, sets it as the default display, and returns
   * it.  gdk_parse_args must have been called first. If the default
   * display has previously been set, simply returns that. An internal
   * function that should not be used by applications.
   * @return The default display, if it could be opened,
   * otherwise <tt>0</tt>.
   */
  static Glib::RefPtr<Display> open_default_libgtk_only();

  
  /** Finds out the DND protocol supported by a window.
   *
   * @newin{2,2}
   * @param xid The X id of the destination window.
   * @param protocol Location where the supported DND protocol is returned.
   * @return The X id of the window where the drop should happen. This
   * may be @a xid or the X id of a proxy window, or None if @a xid doesn't
   * support Drag and Drop.
   */
  GdkNativeWindow get_drag_protocol(GdkNativeWindow xid, GdkDragProtocol& protocol);

  
  /** Returns the Gdk::Keymap attached to @a display.
   * 
   * @newin{2,2}
   * @return The Gdk::Keymap attached to @a display.
   */
  GdkKeymap* get_keymap();
  
  /** Returns the Gdk::Keymap attached to @a display.
   * 
   * @newin{2,2}
   * @return The Gdk::Keymap attached to @a display.
   */
  const GdkKeymap* get_keymap() const;

  bool set_selection_owner(const Glib::RefPtr<Window>& owner, Glib::ustring& selection, guint32 time_, bool send_event);
  Glib::RefPtr<Window> get_selection_owner(const Glib::ustring& selection);

  /** Send a response to SelectionRequest event.
   *
   * @newin{2,2}
   * @param requestor Window to which to deliver response.
   * @param selection Selection that was requested.
   * @param target Target that was selected.
   * @param property Property in which the selection owner stored the data,
   * or "None" to indicate that the request was rejected.
   * @param time_ Timestamp.
   */
  void selection_send_notify(GdkNativeWindow requestor, Glib::ustring& selection, Glib::ustring& target, Glib::ustring& property, guint32 time_);

  
  /** Flushes any requests queued for the windowing system; this happens automatically
   * when the main loop blocks waiting for new events, but if your application
   * is drawing without returning control to the main loop, you may need
   * to call this function explicitely. A common case where this function
   * needs to be called is when an application is executing drawing commands
   * from a thread other than the thread where the main loop is running.
   * 
   * This is most useful for X11. On windowing systems where requests are
   * handled synchronously, this function will do nothing.
   * 
   * @newin{2,4}
   */
  void flush();
  //TODO: Read the docs to know what the types are really: _WRAP_METHOD(GdkDisplayDeviceHooks* set_device_hooks(const GdkDisplayDeviceHooks *new_hooks), gdk_display_set_device_hooks)
  
  /** Returns <tt>true</tt> if cursors can use an 8bit alpha channel
   * on @a display. Otherwise, cursors are restricted to bilevel
   * alpha (i.e. a mask).
   * 
   * @newin{2,4}
   * @return Whether cursors can have alpha channels.
   */
  bool supports_cursor_alpha() const;
  
  /** Returns <tt>true</tt> if multicolored cursors are supported
   * on @a display. Otherwise, cursors have only a forground
   * and a background color.
   * 
   * @newin{2,4}
   * @return Whether cursors can have multiple colors.
   */
  bool supports_cursor_color() const;
  
  /** Returns the default size to use for cursors on @a display.
   * 
   * @newin{2,4}
   * @return The default cursor size.
   */
  guint get_default_cursor_size() const;
  
  /** Gets the maximal size to use for cursors on @a display.
   * 
   * @newin{2,4}
   * @param width The return location for the maximal cursor width.
   * @param height The return location for the maximal cursor height.
   */
  void get_maximal_cursor_size(guint& width, guint& height);

  
  /** Returns the default group leader window for all toplevel windows
   * on @a display. This window is implicitly created by GDK. 
   * See Gdk::Window::set_group().
   * 
   * @newin{2,4}
   * @return The default group leader window for @a display.
   */
  Glib::RefPtr<Window> get_default_group();
  
  /** Returns the default group leader window for all toplevel windows
   * on @a display. This window is implicitly created by GDK. 
   * See Gdk::Window::set_group().
   * 
   * @newin{2,4}
   * @return The default group leader window for @a display.
   */
  Glib::RefPtr<const Window> get_default_group() const;

  //TODO: wrap the vfuncs, though they are not very useful because people will not derive from this class? murrayc.


  /** Returns whether Gdk::EventOwnerChange events will be 
   * sent when the owner of a selection changes.
   * 
   * @newin{2,6}
   * @return Whether Gdk::EventOwnerChange events will 
   * be sent.
   */
  bool supports_selection_notification() const;
  
  /** Request Gdk::EventOwnerChange events for ownership changes
   * of the selection named by the given atom.
   * 
   * @newin{2,6}
   * @param selection The Gdk::Atom naming the selection for which
   * ownership change notification is requested.
   * @return Whether Gdk::EventOwnerChange events will 
   * be sent.
   */
  bool request_selection_notification(const Glib::ustring& selection);

  
  /** Returns whether the speicifed display supports clipboard
   * persistance; i.e.\ if it's possible to store the clipboard data after an
   * application has quit. On X11 this checks if a clipboard daemon is
   * running.
   * 
   * @newin{2,6}
   * @return <tt>true</tt> if the display supports clipboard persistance.
   */
  bool supports_clipboard_persistence() const;

  /** Issues a request to the clipboard manager to store the clipboard data,
   * saving all available targets.
   * On X11, this is a special program that works according to the freedesktop clipboard specification,
   * available at http://www.freedesktop.org/Standards/clipboard-manager-spec.
   * @newin{2,6}
   *
   * @param clipboard_window A Gdk::Window belonging to the clipboard owner.
   * @param time_ A timestamp.
   */
  void store_clipboard(const Glib::RefPtr<Gdk::Window>& clipboard_window, guint32 time_);

  void store_clipboard(const Glib::RefPtr<Gdk::Window>& clipboard_window, guint32 time_, const Glib::StringArrayHandle& targets);
  

  /** Returns <tt>true</tt> if gdk_window_shape_combine_mask() can
   * be used to create shaped windows on @a display.
   * 
   * @newin{2,10}
   * @return <tt>true</tt> if shaped windows are supported.
   */
  bool supports_shapes() const;
  
  /** Returns <tt>true</tt> if gdk_window_input_shape_combine_mask() can
   * be used to modify the input shape of windows on @a display.
   * 
   * @newin{2,10}
   * @return <tt>true</tt> if windows with modified input shape are supported.
   */
  bool supports_input_shapes() const;
  
  /** Returns <tt>true</tt> if Gdk::Window::set_composited() can be used
   * to redirect drawing on the window using compositing.
   * 
   * Currently this only works on X11 with XComposite and
   * XDamage extensions available.
   * 
   * @newin{2,12}
   * @return <tt>true</tt> if windows may be composited.
   */
  bool supports_composite() const;

  
  Glib::RefPtr<DeviceManager> get_device_manager();
  
  Glib::RefPtr<const DeviceManager> get_device_manager() const;


  /** The closed signal is emitted when the connection to the windowing
   * system for this display is closed.
   *
   * @param is_error true if the display was closed due to an error
   *
   * @par Prototype:
   * <tt>void on_my_%closed(bool is_error)</tt>
   */

  Glib::SignalProxy1< void,bool > signal_closed();


public:

public:
  //C++ methods used to invoke GTK+ virtual functions:

protected:
  //GTK+ Virtual Functions (override these to change behaviour):

  //Default Signal Handlers::
  virtual void on_closed(bool is_error);


};

} /* namespace Gdk */


namespace Glib
{
  /** A Glib::wrap() method for this object.
   * 
   * @param object The C instance.
   * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
   * @result A C++ instance that wraps this C instance.
   *
   * @relates Gdk::Display
   */
  Glib::RefPtr<Gdk::Display> wrap(GdkDisplay* object, bool take_copy = false);
}


#endif /* _GDKMM_DISPLAY_H */

