/* $Id: cellrenderer.hg,v 1.22 2006/05/10 20:59:27 murrayc Exp $ */

/* 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 Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <gtkmm/object.h>
#include <gtkmm/widget.h>
#include <gtkmm/celleditable.h>

_DEFS(gtkmm,gtk)
_PH_INCLUDE(gtkmm/private/object_p.h)
_PH_INCLUDE(gtk/gtkcellrenderer.h)


namespace Gtk
{

_CC_INCLUDE(gtk/gtktypebuiltins.h)

_WRAP_ENUM(CellRendererState, GtkCellRendererState)
_WRAP_ENUM(CellRendererMode, GtkCellRendererMode)

/** CellRenderers are used by Gtk::TreeView columns to render the Gtk::TreeModel column data appropriately.
 * They display, and allow editing of, the values of their properties.
 * In most cases, Gtk::TreeView::append_column() will automatically choose the appropriate renderer for the mode column's data type,
 * so you will rarely need to worry about these classes.
 *
 * @ingroup TreeView
 */
class CellRenderer : public Gtk::Object
{
  _CLASS_GTKOBJECT(CellRenderer,GtkCellRenderer,GTK_CELL_RENDERER,Gtk::Object,GtkObject)
public:

  _WRAP_METHOD(void get_size(
                  Widget& widget,
                  const Gdk::Rectangle& cell_area,
                  int& x_offset, int& y_offset,
                  int& width,    int& height) const, gtk_cell_renderer_get_size)

  /** Obtains the width and height needed to render the cell. Used by view widgets
   * to determine the appropriate size for the cell_area passed to
   * render().  Fills in the x and y
   * offsets of the cell relative to this location.  Please note that the
   * values set in @a width  and @a height , as well as those in @a x_offset  and @a y_offset
   * are inclusive of the xpad and ypad properties.
   * @param widget The widget the renderer is rendering to.
   * @param x_offset Location to return x offset of cell relative to @a cell_area.
   * @param y_offset Location to return y offset of cell relative to @a cell_area.
   * @param width Location to return width needed to render a cell.
   * @param height Location to return height needed to render a cell.
   */
  void get_size(Widget& widget, int& x_offset, int& y_offset, int& width, int& height) const;

  _WRAP_METHOD(void render(
                  const Glib::RefPtr<Gdk::Window>& window,
                  Widget& widget,
                  const Gdk::Rectangle& background_area,
                  const Gdk::Rectangle& cell_area,
                  const Gdk::Rectangle& expose_area,
                  CellRendererState flags), gtk_cell_renderer_render)

  _WRAP_METHOD(bool activate(
                  GdkEvent* event,
                  Widget& widget,
                  const Glib::ustring& path,
                  const Gdk::Rectangle& background_area,
                  const Gdk::Rectangle& cell_area,
                  CellRendererState flags), gtk_cell_renderer_activate)

  _WRAP_METHOD(CellEditable* start_editing(
                  GdkEvent* event, Widget& widget,
                  const Glib::ustring& path,
                  const Gdk::Rectangle& background_area,
                  const Gdk::Rectangle& cell_area,
                  CellRendererState flags = CellRendererState(0)), gtk_cell_renderer_start_editing)

  _WRAP_METHOD(void set_fixed_size(int width, int height), gtk_cell_renderer_set_fixed_size)
  _WRAP_METHOD(void get_fixed_size(int& width, int& height) const, gtk_cell_renderer_get_fixed_size)

  _WRAP_METHOD(void editing_canceled(), gtk_cell_renderer_editing_canceled, deprecated "Use stop_editing().")

  _WRAP_METHOD(void stop_editing(bool canceled = false), gtk_cell_renderer_stop_editing)

  /** Returns the property that this CellRenderer renders.
   * For instance, property_text for CellRendererText, and property_active for CellRendererToggle
   * Needs to be overridden in derived classes.
   */
#ifdef GLIBMM_PROPERTIES_ENABLED
  virtual Glib::PropertyProxy_Base _property_renderable();
#else
  virtual Glib::ustring _property_renderable();
#endif

  /** This signal is emitted when the user cancels the process of editing a
   * cell.  For example, an editable cell renderer could be written to cancel
   * editing when the user presses Escape. 
   *
   * @see editing_canceled() 
   */
  _WRAP_SIGNAL(void editing_canceled(), editing_canceled)
  
  //We use no_default_handler for this, because we can not add a new vfunc to 2.5 without breaking ABI.
  //TODO: Remove no_default_handler when we do an ABI-break-with-parallel-install.
  //TODO: Remove the warning in the documentation when we have fixed the inheritance of CellRendererCombo.
  /** This signal gets emitted when a cell starts to be edited.
   * The indended use of this signal is to do special setup
   * on @a editable, e.g. adding an EntryCompletion or setting
   * up additional columns in a ComboBox.
   *
   * Note that GTK+ doesn't guarantee that cell renderers will
   * continue to use the same kind of widget for editing in future
   * releases, therefore you should check the type of @a editable
   * before doing any specific setup.
   *
   * Note that this signal does not work yet in gtkmm.
   * See http://bugzilla.gnome.org/show_bug.cgi?id=301597
   *
   * @newin2p6
   *
   * @param editable the CellEditable.
   * @param path the path identifying the edited cell.
   */
  _WRAP_SIGNAL(void editing_started(CellEditable* editable, const Glib::ustring& path), editing_started, no_default_handler)

  _WRAP_PROPERTY("mode", CellRendererMode)
  _WRAP_PROPERTY("visible", bool)
  _WRAP_PROPERTY("sensitive", bool)
  _WRAP_PROPERTY("xalign", float)
  _WRAP_PROPERTY("yalign", float)
  _WRAP_PROPERTY("xpad", unsigned int)
  _WRAP_PROPERTY("ypad", unsigned int)
  _WRAP_PROPERTY("width", int)
  _WRAP_PROPERTY("height", int)
  _WRAP_PROPERTY("is-expander", bool)
  _WRAP_PROPERTY("is-expanded", bool)
  _WRAP_PROPERTY("cell-background", Glib::ustring)
  _WRAP_PROPERTY("cell-background-gdk", Gdk::Color) 
  _WRAP_PROPERTY("cell-background-set", bool)

protected:
  _CTOR_DEFAULT()

  /** Override this in derived CellRenderers.
   *
   * Obtains the width and height needed to render the cell. Used by view widgets
   * to determine the appropriate size for the cell_area passed to
   * render().  If @a cell_area is not 0, fills in the x and y
   * offsets (if set) of the cell relative to this location.  Please note that the
   * values set in @a width and @a height, as well as those in @a x_offset and @a y_offset
   * are inclusive of the xpad and ypad properties.
   *
   * @param widget The widget the renderer is rendering to.
   * @param cell_area The area a cell will be allocated, or 0.
   * @param x_offset x offset of cell relative to @a cell_area.
   * @param y_offset y offset of cell relative to @a cell_area.
   * @param width Width needed to render a cell.
   * @param height Height needed to render a cell.
   **/
  _WRAP_VFUNC(void get_size(
                  Widget& widget,
                  const Gdk::Rectangle* cell_area,
                  int* x_offset, int* y_offset,
                  int* width,    int* height) const, get_size)
                  
#m4begin
dnl This extra conversion does the extra reference, often needed by code for vfuncs and signal.
_CONVERSION(`GdkDrawable*',`const Glib::RefPtr<Gdk::Drawable>&', `Glib::wrap($3, true)')
#m4end

  _WRAP_VFUNC(void render(
                  const Glib::RefPtr<Gdk::Drawable>& window,
                  Widget& widget,
                  const Gdk::Rectangle& background_area,
                  const Gdk::Rectangle& cell_area,
                  const Gdk::Rectangle& expose_area,
                  CellRendererState flags), render)

  _WRAP_VFUNC(bool activate(
                  GdkEvent* event,
                  Widget& widget,
                  const Glib::ustring& path,
                  const Gdk::Rectangle& background_area,
                  const Gdk::Rectangle& cell_area,
                  CellRendererState flags), activate)

  _WRAP_VFUNC(CellEditable* start_editing(
                  GdkEvent* event,
                  Widget& widget,
                  const Glib::ustring& path,
                  const Gdk::Rectangle& background_area,
                  const Gdk::Rectangle& cell_area,
                  CellRendererState flags), start_editing)
};

} // namespace Gtk

