GNOME.org
 

[gtkmm] Added class overview documentation for new classes.

commit 22d53c04c7d943d0f8f0bd6ccd3f426d860ec653
Author: Murray Cumming <murrayc murrayc com>
Date:   Wed Feb 23 11:06:41 2011 +0100

    Added class overview documentation for new classes.
    
    * gdk/src/devicemanager.hg:
    * gdk/src/rgba.hg:
    * gtk/src/buildable.hg:
    * gtk/src/cellarea.hg:
    * gtk/src/cellareabox.hg:
    * gtk/src/cssprovider.hg:
    * gtk/src/numerableicon.hg:
    * gtk/src/stylecontext.hg:
    * gtk/src/styleprovider.hg:
    * gtk/src/widgetpath.hg: Added documentation based on the C documentation,
    though I have not yet translated the C code examples. I added TODO comments
    so we remember to do them sometime in the future.

 ChangeLog                |   17 ++++++++++
 gdk/src/devicemanager.hg |   79 ++++++++++++++++++++++++++++++++++++++++++++-
 gdk/src/rgba.hg          |    7 +++-
 gtk/src/buildable.hg     |   10 +++++-
 gtk/src/cellarea.hg      |   64 ++++++++++++++++++++++++++++++++++++-
 gtk/src/cellareabox.hg   |   17 +++++++++-
 gtk/src/cssprovider.hg   |   13 +++++++-
 gtk/src/numerableicon.hg |    8 ++++-
 gtk/src/stylecontext.hg  |   57 ++++++++++++++++++++++++++++++++-
 gtk/src/styleprovider.hg |    3 +-
 gtk/src/widgetpath.hg    |   10 +++++-
 11 files changed, 273 insertions(+), 12 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index e8be530..e38eeee 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,22 @@
 2011-02-23  Murray Cumming  <murrayc murrayc com>
 
+	Added class overview documentation for new classes.
+
+	* gdk/src/devicemanager.hg:
+	* gdk/src/rgba.hg:
+	* gtk/src/buildable.hg:
+	* gtk/src/cellarea.hg:
+	* gtk/src/cellareabox.hg:
+	* gtk/src/cssprovider.hg:
+	* gtk/src/numerableicon.hg:
+	* gtk/src/stylecontext.hg:
+	* gtk/src/styleprovider.hg:
+	* gtk/src/widgetpath.hg: Added documentation based on the C documentation, 
+	though I have not yet translated the C code examples. I added TODO comments 
+	so we remember to do them sometime in the future.
+
+2011-02-23  Murray Cumming  <murrayc murrayc com>
+
 	CssProvider: load_from_data(): Added documentation.
 
 	* gtk/src/cssprovider.hg: load_from_data(): Add doxygen documentation 
diff --git a/gdk/src/devicemanager.hg b/gdk/src/devicemanager.hg
index 63430dd..7f8cb10 100644
--- a/gdk/src/devicemanager.hg
+++ b/gdk/src/devicemanager.hg
@@ -31,8 +31,83 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace Gdk
 {
 
-/** TODO
- * @newin{2,26}
+/** Functions for handling input devices.
+ *
+ * In addition to a single pointer and keyboard for user interface input,
+ * GDK contains support for a variety of input devices, including graphics
+ * tablets, touchscreens and multiple pointers/keyboards interacting
+ * simultaneously with the user interface. Under X, the support for multiple
+ * input devices is done through the XInput 2 extension,
+ * which also supports additional features such as sub-pixel positioning
+ * information and additional device-dependent information.
+ *
+ * By default, and if the platform supports it, GDK is aware of multiple
+ * keyboard/pointer pairs and multitouch devices, this behavior can be
+ * changed by calling gdk_disable_multidevice() before Gdk::Display::open(),
+ * although there would rarely be a reason to do that. For a widget or
+ * window to be dealt as multipointer aware,
+ * Gdk::Window::set_support_multidevice() or
+ * Gtk::Widget::set_support_multidevice() must have been called on it.
+ *
+ * Conceptually, in multidevice mode there are 2 device types. Virtual
+ * devices (or master devices) are represented by the pointer cursors
+ * and keyboard foci that are seen on the screen. Physical devices (or
+ * slave devices) represent the hardware that is controlling the virtual
+ * devices, and thus have no visible cursor on the screen.
+ *
+ * Virtual devices are always paired, so there is a keyboard device for every
+ * pointer device. Associations between devices may be inspected through
+ * Gdk::Device::get_associated_device().
+ *
+ * There may be several virtual devices, and several physical devices could
+ * be controlling each of these virtual devices. Physical devices may also
+ * be "floating", which means they are not attached to any virtual device.
+ *
+ * By default, GDK will automatically listen for events coming from all
+ * master devices, setting the Gdk::Device for all events coming from input
+ * devices,
+ * 
+ * Events containing device information are GDK_MOTION_NOTIFY,
+ * GDK_BUTTON_PRESS, GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS,
+ * GDK_BUTTON_RELEASE, GDK_SCROLL, GDK_KEY_PRESS, GDK_KEY_RELEASE,
+ * GDK_ENTER_NOTIFY, GDK_LEAVE_NOTIFY, GDK_FOCUS_CHANGE,
+ * GDK_PROXIMITY_IN, GDK_PROXIMITY_OUT, GDK_DRAG_ENTER, GDK_DRAG_LEAVE,
+ * GDK_DRAG_MOTION, GDK_DRAG_STATUS, GDK_DROP_START, GDK_DROP_FINISHED
+ * and GDK_GRAB_BROKEN.
+ * 
+ * Although gdk_window_set_support_multidevice() must be called on
+ * #GdkWindows in order to support additional features of multiple pointer
+ * interaction, such as multiple per-device enter/leave events, the default
+ * setting will emit just one enter/leave event pair for all devices on the
+ * window. See Gdk::Window::set_support_multidevice() documentation for more
+ * information.
+ *
+ * In order to listen for events coming from other than a virtual device,
+ * Gdk::Window::set_device_events() must be called. Generally, this method
+ * can be used to modify the event mask for any given device.
+ *
+ * Input devices may also provide additional information besides X/Y.
+ * For example, graphics tablets may also provide pressure and X/Y tilt
+ * information. This information is device-dependent, and may be
+ * queried through Gdk::Devie::get_axis(). In multidevice mode, virtual
+ * devices will change axes in order to always represent the physical
+ * device that is routing events through it. Whenever the physical device
+ * changes, the Gdk::Device::property_n_axes() property will be notified, and
+ * Gdk::Device::list_axes() will return the new device axes.
+ *
+ * Devices may also have associated keys or
+ * macro buttons. Such keys can be globally set to map into normal X
+ * keyboard events. The mapping is set using Gdk::Device::set_key().
+ *
+ * In order to query the device hierarchy and be aware of changes in the
+ * device hierarchy (such as virtual devices being created or removed, or
+ * physical devices being plugged or unplugged), GDK provides
+ * Gdk::DeviceManager. On X11, multidevice support is implemented through
+ * XInput 2. Unless gdk_disable_multidevice() is called, the XInput 2.x
+ * Gdk::DeviceManager implementation will be used as the input source. Otherwise
+ * either the core or XInput 1.x implementations will be used.
+ *
+ * @newin{3,0}
  */
 class DeviceManager : public Glib::Object
 {
diff --git a/gdk/src/rgba.hg b/gdk/src/rgba.hg
index f0e9f22..b3e2031 100644
--- a/gdk/src/rgba.hg
+++ b/gdk/src/rgba.hg
@@ -22,7 +22,12 @@ _DEFS(gdkmm,gdk)
 namespace Gdk
 {
 
-/** TODO
+/** An RGBA Color.
+ * The RGBA class is a convenient way to pass rgba colors around. 
+ * It's based on cairo's way to deal with (possibly translucent) colors and mirrors its behavior. 
+ * All values are in the range from 0.0 to 1.0 inclusive. 
+ * So the color (0.0, 0.0, 0.0, 0.0) represents transparent black and (1.0, 1.0, 1.0, 1.0) is opaque white. 
+ * Other values will be clamped to this range when drawing. 
  */
 class RGBA
 {
diff --git a/gtk/src/buildable.hg b/gtk/src/buildable.hg
index 0e3f960..953d687 100644
--- a/gtk/src/buildable.hg
+++ b/gtk/src/buildable.hg
@@ -32,9 +32,15 @@ typedef struct _GtkBuildableIface GtkBuildableIface;
 namespace Gtk
 {
 
-/** TODO.
+/** A base class for objects that can be built by Gtk::Builder.
  *
- * @newin3p0
+ * Buildable allows objects to extend and customize thier deserialization from Gtk::Builder UI descriptions. 
+ * The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects.
+ *
+ * All gtkmm widgets, and many non-widget objects, derive from this base class. 
+ * The main user of this interface is Gtk::Builder. There should be very little need for applications to call any of Buildable's methods.
+ * 
+ * @newin{3,0}
  */
 class Buildable : public Glib::Interface
 {
diff --git a/gtk/src/cellarea.hg b/gtk/src/cellarea.hg
index 7379fdd..c6dffc7 100644
--- a/gtk/src/cellarea.hg
+++ b/gtk/src/cellarea.hg
@@ -26,7 +26,69 @@ _PINCLUDE(gtkmm/private/object_p.h)
 namespace Gtk
 {
 
-/** TODO
+//TODO: This documentation omits the examples from the C documentation. We should translate them to C++.
+//TODO: Find a way to markup the section titles in this doxygen comment.
+/** An abstract base class for laying out CellRenderers.
+ *
+ * This is an abstract base class for CellLayout widgets
+ * (also referred to as "layouting widgets") to interface with an
+ * arbitrary number of CellRenderers and interact with the user
+ * for a given TreeModel row.
+ *
+ * The cell area handles events, focus navigation, drawing and
+ * size requests and allocations for a given row of data.
+ *
+ * Usually users dont have to interact with the CellArea directly
+ * unless they are implementing a cell layouting widget themselves.
+ *
+ * Requesting area sizes
+ * 
+ * As outlined in Gtk::Widget's
+ * geometry management description, GTK+ uses a height-for-width
+ * geometry management system to compute the sizes of widgets and user
+ * interfaces. CellArea uses the same semantics to calculate the
+ * size of an area for an arbitrary number of TreeModel rows.
+ *
+ * When requesting the size of a cell area one needs to calculate
+ * the size for a handful of rows, and this will be done differently by
+ * different layouting widgets. For instance a TreeViewColumn
+ * always lines up the areas from top to bottom while an IconView,
+ * on the other hand, might enforce that all areas received the same
+ * width and wrap the areas around, requesting height for more cell
+ * areas when allocated less width.
+ *
+ * It's also important for areas to maintain some cell
+ * alignments with areas rendered for adjacent rows (cells can
+ * appear "columnized" inside an area even when the size of
+ * cells are different in each row). For this reason the CellArea
+ * uses a CellAreaContext object to store the alignments
+ * and sizes along the way (as well as the overall largest minimum
+ * and natural size for all the rows which have been calculated
+ * with the said context).
+ *
+ * The CellAreaContext is an opaque object specific to the
+ * CellArea which created it (see CellArea::create_context()).
+ * The owning cell-layouting widget can create as many contexts as
+ * it wishes to calculate sizes of rows which should receive the
+ * same size in at least one orientation (horizontally or vertically).
+ * However, it's important that the same CellAreaContext which
+ * was used to request the sizes for a given TreeModel row be
+ * used when rendering or processing events for that row.
+ *
+ * Cell Properties
+ * 
+ * The CellArea introduces cell propertie
+ * for CellRenderers in very much the same way that Gtk::Container
+ * introduces child properties
+ * for Widgets. This provides some general interfaces for defining
+ * the relationship cell areas have with their cells. For instance in a
+ * CellAreaBox a cell might "expand" and receive extra space when
+ * the area is allocated more than its full natural request, or a cell
+ * might be configured to "align" with adjacent rows which were requested
+ * and rendered with the same CellAreaContext.
+ *
+ * To set the value of a cell property, use cell_set_property(). To obtain
+ * the value of a cell property, use cell_get_property().
  *
  * @newin{3,0}
  */
diff --git a/gtk/src/cellareabox.hg b/gtk/src/cellareabox.hg
index ff0651c..6b88b99 100644
--- a/gtk/src/cellareabox.hg
+++ b/gtk/src/cellareabox.hg
@@ -24,7 +24,22 @@ _PINCLUDE(gtkmm/private/cellarea_p.h)
 namespace Gtk
 {
 
-/** TODO
+/** A cell area that renders CellRenderers into a row or a colum, depending on its orientation.
+ *
+ * This class uses a notion of packing. Packing
+ * refers to adding cell renderers with reference to a particular position
+ * in a CellAreaBox. There are two reference positions: the
+ * start and the end of the box.
+ * When the CellAreaBox is oriented in the Gtk::ORIENTATION_VERTICAL
+ * orientation, the start is defined as the top of the box and the end is
+ * defined as the bottom. In the  Gtk::ORIENTATION_HORIZONTAL orientation
+ * start is defined as the left side and the end is defined as the right
+ * side.
+ *
+ * Alignments of CellRenderers rendered in adjacent rows can be
+ * configured by configuring the align_child cell property
+ * with CellArea::cell_set_property() or by specifying the "align"
+ * argument to pack_start() or pack_end().
  *
  * @newin{3,0}
  */
diff --git a/gtk/src/cssprovider.hg b/gtk/src/cssprovider.hg
index b8711d3..921dcb4 100644
--- a/gtk/src/cssprovider.hg
+++ b/gtk/src/cssprovider.hg
@@ -26,7 +26,18 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace Gtk
 {
 
-/** TODO
+/** CSS-like styling for widgets, implementing the StyleProvider base class.
+ *
+ * It is able to parse <ulink url="http://www.w3.org/TR/CSS2";>CSS</ulink>-like
+ * input in order to style widgets.
+ *
+ * An application can cause GTK+ to parse a specific CSS style sheet by
+ * calling load_from_file() and adding the provider with
+ * StyleContext::add_provider() or StyleContext::add_provider_for_screen().
+ * In addition, certain files will be read when GTK+ is initialized.
+ * See the <ulink url="http://library.gnome.org/devel/gtk3/unstable/GtkCssProvider.html#GtkCssProvider.description";>GtkCssProvider documentation</ulink> for details of these default files and details of the stylesheets.
+ *
+ * @newin{3,0}
  */
 class CssProvider
   : public Glib::Object,
diff --git a/gtk/src/numerableicon.hg b/gtk/src/numerableicon.hg
index d3f5d47..c93a081 100644
--- a/gtk/src/numerableicon.hg
+++ b/gtk/src/numerableicon.hg
@@ -26,7 +26,13 @@ _PINCLUDE(giomm/private/emblemedicon_p.h)
 namespace Gtk
 {
 
-/** TODO
+/** A Gio::Icon that allows numbered emblems.
+ *
+ * GtkNumerableIcon is a subclass of EmblemedIcon that can show a number or short string as an emblem. 
+ * The number can be overlayed on top of another emblem, if desired. 
+ *
+ * It supports theming by taking font and color information from a provided StyleContext. See set_style_context(). 
+ *
  * @newin{3,0}
  */
 class NumerableIcon : public Gio::EmblemedIcon
diff --git a/gtk/src/stylecontext.hg b/gtk/src/stylecontext.hg
index 8e00d12..077f747 100644
--- a/gtk/src/stylecontext.hg
+++ b/gtk/src/stylecontext.hg
@@ -37,7 +37,60 @@ namespace Gtk
 
 class IconSet;
 
-/** TODO
+//TODO: Add (and translate to C++) the code examples from the C documentation.
+//TODO: Find a way to show the headings as headings in this doxygen comment.
+/** This object stores styling information affecting a widget defined by WidgetPath.
+ *
+ * In order to construct the final style information, StyleContext
+ * queries information from all attached StyleProviders. Style providers
+ * can be either attached explicitly to the context through
+ * add_provider(), or to the screen through
+ * add_provider_for_screen(). The resulting style is a
+ * combination of all providers' information in priority order.
+ *
+ * For GTK+ widgets, any StyleContext returned by
+ * Widget::get_style_context() will already have a WidgetPath, a
+ * Gdk::Screen and RTL/LTR information set, The style context will be also
+ * updated automatically if any of these settings change on the widget.
+ *
+ * If you are using the theming layer standalone, you will need to set a
+ * widget path and a screen yourself to the created style context through
+ * set_path() and set_screen(), as well
+ * as updating the context yourself using invalidate()
+ * whenever any of the conditions change, such as a change in the
+ * Settings::property_gtk_theme_name() setting or a hierarchy change in the rendered
+ * widget.
+ *
+ * Transition animations
+ * 
+ * StyleContext has built-in support for state change transitions.
+ * Note that these animations respect the Settings::property_gtk_enable_animations()
+ * setting.
+ *
+ * For simple widgets where state changes affect the whole widget area,
+ * calling notify_state_change() with a no region
+ * is sufficient to trigger the transition animation. And GTK+ already
+ * does that when Widget::set_state() or Widget::set_state_flags()
+ * are called.
+ * 
+ * If a widget needs to declare several animatable regions (i.e. not
+ * affecting the whole widget area), its Widget::signal_draw() signal handler
+ * needs to wrap the render operations for the different regions with
+ * calls to push_animatable_region() and
+ * pop_animatable_region(). These methods take an
+ * identifier for the region which must be unique within the style context.
+ * For simple widgets with a fixed set of animatable regions, using an
+ * enumeration works well.
+ *
+ * For complex widgets with an arbitrary number of animatable regions, it
+ * is up to the implementation to come up with a way to uniquely identify
+ * each animatable region. Using pointers to internal objects is one way
+ * to achieve this.
+ *
+ * The widget also needs to notify the style context about a state change
+ * for a given animatable region so the animation is triggered. 
+ * notify_state_change() can take no region IDs, meaning that the whole widget 
+ * area will be updated by the animation.
  *
  * @newin{3,0}
  */
@@ -126,7 +179,9 @@ public:
 
   _WRAP_METHOD(bool lookup_color(const Glib::ustring& color_name, Gdk::RGBA& color), gtk_style_context_lookup_color)
 
+  //TODO: region_id can be NULL.
   _WRAP_METHOD(void notify_state_change(const Glib::RefPtr<Gdk::Window>& window, gpointer region_id, StateType state, bool state_value), gtk_style_context_notify_state_change)
+  
   _WRAP_METHOD(void push_animatable_region(gpointer region_id), gtk_style_context_push_animatable_region)
   _WRAP_METHOD(void pop_animatable_region(), gtk_style_context_pop_animatable_region)
 
diff --git a/gtk/src/styleprovider.hg b/gtk/src/styleprovider.hg
index 213d436..3b2dd82 100644
--- a/gtk/src/styleprovider.hg
+++ b/gtk/src/styleprovider.hg
@@ -30,7 +30,8 @@ typedef struct _GtkStyleProviderIface GtkStyleProviderIface;
 namespace Gtk
 {
 
-/** TODO
+/**  This is a base class used to provide style information to a StyleContext.
+ * See StyleContext::add_provider() and StyleContext::add_provider_for_screen().
  *
  * @newin{3,0}
  */
diff --git a/gtk/src/widgetpath.hg b/gtk/src/widgetpath.hg
index 8652d36..8eec409 100644
--- a/gtk/src/widgetpath.hg
+++ b/gtk/src/widgetpath.hg
@@ -22,7 +22,15 @@ _DEFS(gtkmm,gtk)
 namespace Gtk
 {
 
-/** TODO
+//TODO: Add all of the C documentation, including translating the code examples to C++.
+/** This represents a widget hierarchy from the topmost widget, typically a toplevel, to any child. 
+ * This widget path abstraction is used in StyleContext on behalf of the real
+ * widget in order to query style information.
+ *
+ * If you are using gtkmm widgets, you probably will not need to use
+ * this API directly, as there is Widget::get_path(), and the style
+ * context returned by Widget::get_style_context() will be automatically
+ * updated on widget hierarchy changes.
  *
  * @newin{3,0}
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]