[cheese] Add more classes to gtk-doc documentation
- From: David King <davidk src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [cheese] Add more classes to gtk-doc documentation
- Date: Fri, 28 Oct 2011 22:48:05 +0000 (UTC)
commit 4a7f476206ce1411315793158178683f9ee2303c
Author: David King <amigadave amigadave com>
Date: Sat Oct 29 00:38:25 2011 +0200
Add more classes to gtk-doc documentation
Add basic documentation for CheeseCamera, CheeseFileUtil and CheeseFlash
classes. Split the API reference into libcheese and libcheese-gtk
chapters.
docs/reference/Makefile.am | 16 ++--
docs/reference/cheese-docs.xml | 26 ++++-
docs/reference/cheese-sections.txt | 144 +++++++++++++++++++--------
docs/reference/cheese.types | 3 +
libcheese/cheese-avatar-chooser.h | 12 +++
libcheese/cheese-camera-device-monitor.c | 32 +++----
libcheese/cheese-camera-device-monitor.h | 2 +-
libcheese/cheese-camera.c | 158 ++++++++++++++++++++++++------
libcheese/cheese-camera.h | 46 +++++++--
libcheese/cheese-fileutil.c | 53 ++++++++++
libcheese/cheese-fileutil.h | 46 ++++++++-
libcheese/cheese-flash.c | 33 ++++++-
libcheese/cheese-flash.h | 23 ++++-
libcheese/cheese-widget.c | 29 ++++--
14 files changed, 486 insertions(+), 137 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 26b933d..d5eefda 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -50,12 +50,8 @@ CFILE_GLOB=$(top_srcdir)/libcheese/*.c
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
-IGNORE_HFILES= \
- cheese-camera.h \
- cheese-aspect-frame.h \
- cheese-fileutil.h \
- cheese-flash.h \
- cheese-widget-private.h \
+IGNORE_HFILES= \
+ cheese-aspect-frame.h \
cheese-enums.h \
um-crop-area.h
@@ -77,9 +73,8 @@ expand_content_files=
# signals and properties.
# e.g. AM_CPPFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
-AM_CPPFLAGS=-I$(top_srcdir) -I$(top_builddir) $(CHEESE_CFLAGS)
-GTKDOC_LIBS=\
- $(CHEESE_LIBS) \
+AM_CFLAGS = $(CHEESE_CFLAGS)
+GTKDOC_LIBS = \
$(top_builddir)/libcheese.la \
$(top_builddir)/libcheese-gtk.la
@@ -93,3 +88,6 @@ include $(top_srcdir)/gtk-doc.make
#TESTS_ENVIRONMENT = cd $(srcdir) &&
#TESTS = $(GTKDOC_CHECK)
#endif
+
+sgml.stamp: $(DOC_MODULE)-sections.txt
+$(DOC_MAIN_SGML_FILE): sgml.stamp
diff --git a/docs/reference/cheese-docs.xml b/docs/reference/cheese-docs.xml
index a397603..4face42 100644
--- a/docs/reference/cheese-docs.xml
+++ b/docs/reference/cheese-docs.xml
@@ -19,15 +19,33 @@
<title>Cheese Overview</title>
<para>
Cheese uses your webcam to take photos and videos, applies fancy special
- effects and lets you share the fun with others
+ effects and lets you share the fun with others. Cheese also provides two
+ libraries for use by other applications: libcheese and libcheese-gtk.
</para>
+ </chapter>
- <xi:include href="xml/cheese-widget.xml"/>
- <xi:include href="xml/cheese-effect.xml"/>
+ <chapter>
+ <title>libcheese</title>
+ <para>
+ libcheese provides video and photo capture functionality which does not
+ require GTK+, such as enumerating video capture devices.
+ </para>
+ <xi:include href="xml/cheese-camera.xml"/>
<xi:include href="xml/cheese-camera-device.xml"/>
<xi:include href="xml/cheese-camera-device-monitor.xml"/>
- <xi:include href="xml/cheese-avatar-chooser.xml"/>
+ <xi:include href="xml/cheese-effect.xml"/>
+ <xi:include href="xml/cheese-file-util.xml"/>
+ </chapter>
+ <chapter>
+ <title>libcheese-gtk</title>
+ <para>
+ libcheese-gtk provides video and photo capture widgets for use in GTK+
+ applications
+ </para>
+ <xi:include href="xml/cheese-avatar-chooser.xml"/>
+ <xi:include href="xml/cheese-flash.xml"/>
+ <xi:include href="xml/cheese-widget.xml"/>
</chapter>
<chapter id="object-tree">
diff --git a/docs/reference/cheese-sections.txt b/docs/reference/cheese-sections.txt
index 18fc322..dc93148 100644
--- a/docs/reference/cheese-sections.txt
+++ b/docs/reference/cheese-sections.txt
@@ -1,44 +1,43 @@
<SECTION>
-<FILE>cheese-widget</FILE>
-<TITLE>CheeseWidget</TITLE>
-CheeseWidgetClass
-CheeseWidget
-cheese_widget_new
-cheese_widget_get_error
-CheeseWidgetState
+<FILE>cheese-avatar-chooser</FILE>
+<TITLE>CheeseAvatarChooser</TITLE>
+CheeseAvatarChooserClass
+CheeseAvatarChooser
+cheese_avatar_chooser_new
+cheese_avatar_chooser_get_picture
<SUBSECTION Standard>
-CHEESE_WIDGET
-CHEESE_IS_WIDGET
-CHEESE_TYPE_WIDGET
-cheese_widget_get_type
-CHEESE_WIDGET_CLASS
-CHEESE_IS_WIDGET_CLASS
-CHEESE_WIDGET_GET_CLASS
+CHEESE_AVATAR_CHOOSER
+CHEESE_IS_AVATAR_CHOOSER
+CHEESE_TYPE_AVATAR_CHOOSER
+cheese_avatar_chooser_get_type
+CHEESE_AVATAR_CHOOSER_CLASS
+CHEESE_IS_AVATAR_CHOOSER_CLASS
+CHEESE_AVATAR_CHOOSER_GET_CLASS
</SECTION>
<SECTION>
-<FILE>cheese-effect</FILE>
-<TITLE>CheeseEffect</TITLE>
-CheeseEffect
-CheeseEffectClass
-cheese_effect_new
-cheese_effect_enable_preview
-cheese_effect_disable_preview
+<FILE>cheese-camera</FILE>
+<TITLE>CheeseCamera</TITLE>
+CheeseCameraClass
+CheeseCamera
+cheese_camera_new
+cheese_camera_setup
+CheeseCameraError
<SUBSECTION Standard>
-CHEESE_EFFECT
-CHEESE_IS_EFFECT
-CHEESE_TYPE_EFFECT
-cheese_effect_get_type
-CHEESE_EFFECT_CLASS
-CHEESE_IS_EFFECT_CLASS
-CHEESE_EFFECT_GET_CLASS
+CHEESE_CAMERA
+CHEESE_IS_CAMERA
+CHEESE_TYPE_CAMERA
+cheese_camera_get_type
+CHEESE_CAMERA_CLASS
+CHEESE_IS_CAMERA_CLASS
+CHEESE_CAMERA_GET_CLASS
</SECTION>
<SECTION>
<FILE>cheese-camera-device</FILE>
<TITLE>CheeseCameraDevice</TITLE>
-CheeseCameraDevice
CheeseCameraDeviceClass
+CheeseCameraDevice
cheese_camera_device_new
cheese_camera_device_get_name
cheese_camera_device_get_id
@@ -71,19 +70,80 @@ CHEESE_CAMERA_DEVICE_MONITOR_GET_CLASS
</SECTION>
<SECTION>
-<FILE>cheese-avatar-chooser</FILE>
-<TITLE>CheeseAvatarChooser</TITLE>
-CheeseAvatarChooserClass
-CheeseAvatarChooser
-cheese_avatar_chooser_new
-cheese_avatar_chooser_get_picture
+<FILE>cheese-effect</FILE>
+<TITLE>CheeseEffect</TITLE>
+CheeseEffectClass
+CheeseEffect
+cheese_effect_new
+cheese_effect_enable_preview
+cheese_effect_disable_preview
<SUBSECTION Standard>
-CHEESE_AVATAR_CHOOSER
-CHEESE_IS_AVATAR_CHOOSER
-CHEESE_TYPE_AVATAR_CHOOSER
-cheese_avatar_chooser_get_type
-CHEESE_AVATAR_CHOOSER_CLASS
-CHEESE_IS_AVATAR_CHOOSER_CLASS
-CHEESE_AVATAR_CHOOSER_GET_CLASS
+CHEESE_EFFECT
+CHEESE_IS_EFFECT
+CHEESE_TYPE_EFFECT
+cheese_effect_get_type
+CHEESE_EFFECT_CLASS
+CHEESE_IS_EFFECT_CLASS
+CHEESE_EFFECT_GET_CLASS
</SECTION>
+<SECTION>
+<FILE>cheese-file-util</FILE>
+<TITLE>CheeseFileUtil</TITLE>
+CheeseFileUtilClass
+CheeseFileUtil
+cheese_fileutil_new
+CHEESE_PHOTO_NAME_SUFFIX
+CHEESE_VIDEO_NAME_SUFFIX
+CheeseMediaMode
+cheese_fileutil_get_new_media_filename
+cheese_fileutil_get_path_before_224
+cheese_fileutil_get_photo_path
+cheese_fileutil_get_video_path
+cheese_fileutil_reset_burst
+<SUBSECTION Standard>
+CHEESE_FILEUTIL
+CHEESE_IS_FILEUTIL
+CHEESE_TYPE_FILEUTIL
+cheese_fileutil_get_type
+CHEESE_FILEUTIL_CLASS
+CHEESE_IS_FILEUTIL_CLASS
+CHEESE_FILEUTIL_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>cheese-flash</FILE>
+<TITLE>CheeseFlash</TITLE>
+CheeseFlashClass
+CheeseFlash
+cheese_flash_new
+cheese_flash_fire
+<SUBSECTION Standard>
+CHEESE_FLASH
+CHEESE_IS_FLASH
+CHEESE_TYPE_FLASH
+cheese_flash_get_type
+CHEESE_FLASH_CLASS
+CHEESE_IS_FLASH_CLASS
+CHEESE_FLASH_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>cheese-widget</FILE>
+<TITLE>CheeseWidget</TITLE>
+CheeseWidgetClass
+CheeseWidget
+cheese_widget_new
+cheese_widget_get_camera
+cheese_widget_get_error
+cheese_widget_get_video_area
+CheeseWidgetState
+<SUBSECTION Standard>
+CHEESE_WIDGET
+CHEESE_IS_WIDGET
+CHEESE_TYPE_WIDGET
+cheese_widget_get_type
+CHEESE_WIDGET_CLASS
+CHEESE_IS_WIDGET_CLASS
+CHEESE_WIDGET_GET_CLASS
+</SECTION>
diff --git a/docs/reference/cheese.types b/docs/reference/cheese.types
index f1800cb..c8803fd 100644
--- a/docs/reference/cheese.types
+++ b/docs/reference/cheese.types
@@ -1,6 +1,9 @@
cheese_avatar_chooser_get_type
cheese_camera_device_get_type
cheese_camera_device_monitor_get_type
+cheese_camera_get_type
cheese_effect_get_type
+cheese_fileutil_get_type
+cheese_flash_get_type
cheese_video_format_get_type
cheese_widget_get_type
diff --git a/libcheese/cheese-avatar-chooser.h b/libcheese/cheese-avatar-chooser.h
index 369558a..38e912d 100644
--- a/libcheese/cheese-avatar-chooser.h
+++ b/libcheese/cheese-avatar-chooser.h
@@ -38,13 +38,25 @@ G_BEGIN_DECLS
typedef struct _CheeseAvatarChooserClass CheeseAvatarChooserClass;
typedef struct _CheeseAvatarChooser CheeseAvatarChooser;
+/**
+ * CheeseAvatarChooserClass:
+ *
+ * Use the accessor functions below.
+ */
struct _CheeseAvatarChooserClass
{
+ /*< private >*/
GtkDialogClass parent_class;
};
+/**
+ * CheeseAvatarChooser:
+ *
+ * Use the accessor functions below.
+ */
struct _CheeseAvatarChooser
{
+ /*< private >*/
GtkDialog parent_instance;
};
diff --git a/libcheese/cheese-camera-device-monitor.c b/libcheese/cheese-camera-device-monitor.c
index 2c6b696..efb9b7f 100644
--- a/libcheese/cheese-camera-device-monitor.c
+++ b/libcheese/cheese-camera-device-monitor.c
@@ -51,8 +51,8 @@
* @stability: Unstable
* @include: cheese/cheese-camera-device-monitor.h
*
- * #CheeseCameraDeviceMonitor provides a basic interface for
- * video4linux device enumeration and hotplugging.
+ * #CheeseCameraDeviceMonitor provides a basic interface for video4linux device
+ * enumeration and hotplugging.
*
* It uses either GUdev or some platform specific code to list video devices.
* It is also capable (right now in Linux only, with the udev backend) to
@@ -228,10 +228,9 @@ cheese_camera_device_monitor_uevent_cb (GUdevClient *client,
* cheese_camera_device_monitor_coldplug:
* @monitor: a #CheeseCameraDeviceMonitor object.
*
- * Will actively look for plugged in cameras and emit
- * ::added for those new cameras.
- * This is only required when your program starts, so as to connect
- * to those signals before they are emitted.
+ * Will actively look for plugged in cameras and emit ::added for those new
+ * cameras. This is only required when your program starts, so as to connect to
+ * those signals before they are emitted.
*/
void
cheese_camera_device_monitor_coldplug (CheeseCameraDeviceMonitor *monitor)
@@ -363,15 +362,12 @@ cheese_camera_device_monitor_class_init (CheeseCameraDeviceMonitorClass *klass)
/**
* CheeseCameraDeviceMonitor::added:
- * @device: A private object representing the newly added camera.
- * @id: Device unique identifier.
- * @device: Device file name (e.g. /dev/video2).
- * @product_name: Device product name (human readable, intended to be displayed in a UI).
- * @api_version: Supported video4linux API: 1 for v4l, 2 for v4l2.
+ * @monitor: the #CheeseCameraDeviceMonitor that emitted the signal
+ * @device: a new #CheeseCameraDevice representing the video capture device
*
* The ::added signal is emitted when a camera is added, or on start-up
- * after #cheese_camera_device_monitor_colplug is called.
- **/
+ * after cheese_camera_device_monitor_coldplug() is called.
+ */
monitor_signals[ADDED] = g_signal_new ("added", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseCameraDeviceMonitorClass, added),
@@ -381,12 +377,12 @@ cheese_camera_device_monitor_class_init (CheeseCameraDeviceMonitorClass *klass)
/**
* CheeseCameraDeviceMonitor::removed:
- * @device: A private object representing the newly added camera
- * @id: Device unique identifier.
+ * @monitor: the #CheeseCameraDeviceMonitor that emitted the signal
+ * @uuid: UUID for the device on the system
*
- * The ::removed signal is emitted when a camera is un-plugged, or
- * disabled on the system.
- **/
+ * The ::removed signal is emitted when a camera is unplugged, or disabled on
+ * the system.
+ */
monitor_signals[REMOVED] = g_signal_new ("removed", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseCameraDeviceMonitorClass, removed),
diff --git a/libcheese/cheese-camera-device-monitor.h b/libcheese/cheese-camera-device-monitor.h
index 88e9d47..bbec215 100644
--- a/libcheese/cheese-camera-device-monitor.h
+++ b/libcheese/cheese-camera-device-monitor.h
@@ -66,7 +66,7 @@ struct _CheeseCameraDeviceMonitorClass
/*< public >*/
void (*added)(CheeseCameraDeviceMonitor *monitor,
CheeseCameraDevice *device);
- void (*removed)(CheeseCameraDeviceMonitor *monitor, const char *id);
+ void (*removed)(CheeseCameraDeviceMonitor *monitor, const char *uuid);
};
GType cheese_camera_device_monitor_get_type (void) G_GNUC_CONST;
diff --git a/libcheese/cheese-camera.c b/libcheese/cheese-camera.c
index 788ff34..107d26b 100644
--- a/libcheese/cheese-camera.c
+++ b/libcheese/cheese-camera.c
@@ -37,6 +37,17 @@
#include "cheese-camera-device.h"
#include "cheese-camera-device-monitor.h"
+/**
+ * SECTION:cheese-camera
+ * @short_description: A representation of the video capture device inside
+ * #CheeseWidget
+ * @stability: Unstable
+ * @include: cheese/cheese-camera.h
+ *
+ * #CheeseCamera represents the video capture device used to drive a
+ * #CheeseWidget.
+ */
+
G_DEFINE_TYPE (CheeseCamera, cheese_camera, G_TYPE_OBJECT)
#define CHEESE_CAMERA_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), CHEESE_TYPE_CAMERA, CheeseCameraPrivate))
@@ -244,6 +255,15 @@ cheese_camera_bus_message_cb (GstBus *bus, GstMessage *message, CheeseCamera *ca
}
}
+/*
+ * cheese_camera_add_device:
+ * @monitor: a #CheeseCameraDeviceMonitor
+ * @device: a #CheeseCameraDevice
+ * @camera: a #CheeseCamera
+ *
+ * Handle the CheeseCameraDeviceMonitor::added signal and add the new
+ * #CheeseCameraDevice to the list of current devices.
+ */
static void
cheese_camera_add_device (CheeseCameraDeviceMonitor *monitor,
CheeseCameraDevice *device,
@@ -255,9 +275,19 @@ cheese_camera_add_device (CheeseCameraDeviceMonitor *monitor,
priv->num_camera_devices++;
}
+/*
+ * cheese_camera_remove_device:
+ * @monitor: a #CheeseCameraDeviceMonitor
+ * @uuid: UUId of a #CheeseCameraDevice
+ * @camera: a #CheeseCamera
+ *
+ * Handle the CheeseCameraDeviceMonitor::removed signal and remove the
+ * #CheeseCameraDevice associated with the UUID from the list of current
+ * devices.
+ */
static void
cheese_camera_remove_device (CheeseCameraDeviceMonitor *monitor,
- gchar *id,
+ gchar *uuid,
CheeseCamera *camera)
{
int i;
@@ -269,7 +299,7 @@ cheese_camera_remove_device (CheeseCameraDeviceMonitor *monitor,
CheeseCameraDevice *indexDevice = (CheeseCameraDevice *) g_ptr_array_index (priv->camera_devices, i);
const gchar *indexDeviceId = cheese_camera_device_get_id (indexDevice);
- if (strcmp (indexDeviceId, id) == 0)
+ if (strcmp (indexDeviceId, uuid) == 0)
{
g_ptr_array_remove (priv->camera_devices, (gpointer) indexDevice);
priv->num_camera_devices--;
@@ -278,6 +308,13 @@ cheese_camera_remove_device (CheeseCameraDeviceMonitor *monitor,
}
}
+/*
+ * cheese_camera_detect_camera_devices:
+ * @camera: a #CheeseCamera
+ *
+ * Enumerate the physical camera devices present on the system, and add them to
+ * the list of #CheeseCameraDevice objects.
+ */
static void
cheese_camera_detect_camera_devices (CheeseCamera *camera)
{
@@ -522,9 +559,8 @@ cheese_camera_get_num_camera_devices (CheeseCamera *camera)
* cheese_camera_get_selected_device:
* @camera: a #CheeseCamera
*
- * Returns: (transfer none): a #CheeseCameraDevice or NULL
+ * Returns: (transfer none): a #CheeseCameraDevice or %NULL
*/
-
CheeseCameraDevice *
cheese_camera_get_selected_device (CheeseCamera *camera)
{
@@ -537,6 +573,12 @@ cheese_camera_get_selected_device (CheeseCamera *camera)
return NULL;
}
+/*
+ * cheese_camera_device_switch_camera_device:
+ * @camera: a #CheeseCamera
+ *
+ * Toggle the playing/recording state of the #CheeseCamera.
+ */
void
cheese_camera_switch_camera_device (CheeseCamera *camera)
{
@@ -573,8 +615,10 @@ cheese_camera_switch_camera_device (CheeseCamera *camera)
/**
* cheese_camera_play:
* @camera: a #CheeseCamera
+ *
+ * Set the state of the GStreamer pipeline associated with the #CheeseCamera to
+ * playing.
*/
-
void
cheese_camera_play (CheeseCamera *camera)
{
@@ -608,8 +652,10 @@ cheese_camera_play (CheeseCamera *camera)
/**
* cheese_camera_stop:
* @camera: a #CheeseCamera
+ *
+ * Set the state of the GStreamer pipeline associated with the #CheeseCamera to
+ * NULL.
*/
-
void
cheese_camera_stop (CheeseCamera *camera)
{
@@ -702,8 +748,9 @@ cheese_camera_element_from_effect (CheeseCamera *camera, CheeseEffect *effect)
* cheese_camera_set_effect:
* @camera: a #CheeseCamera
* @effect: a #CheeseEffect
+ *
+ * Set the @effect on the @camera.
*/
-
void
cheese_camera_set_effect (CheeseCamera *camera, CheeseEffect *effect)
{
@@ -717,9 +764,10 @@ cheese_camera_set_effect (CheeseCamera *camera, CheeseEffect *effect)
/**
* cheese_camera_toggle_effects_pipeline:
* @camera: a #CheeseCamera
- * @active: TRUE is effects pipeline is active, FALSE otherwise
+ * @active: %TRUE is effects pipeline is active, %FALSE otherwise
+ *
+ * Control whether the effects pipeline is enabled for @camera.
*/
-
void
cheese_camera_toggle_effects_pipeline (CheeseCamera *camera, gboolean active)
{
@@ -743,7 +791,6 @@ cheese_camera_toggle_effects_pipeline (CheeseCamera *camera, gboolean active)
* @effect: a #CheeseEffect
* @texture: a #ClutterTexture
*/
-
void
cheese_camera_connect_effect_texture (CheeseCamera *camera, CheeseEffect *effect, ClutterTexture *texture)
{
@@ -788,8 +835,9 @@ cheese_camera_connect_effect_texture (CheeseCamera *camera, CheeseEffect *effect
* cheese_camera_start_video_recording:
* @camera: a #CheeseCamera
* @filename: the name of the video file that should be recorded
+ *
+ * Start a video recording with the @camera and save it to @filename.
*/
-
void
cheese_camera_start_video_recording (CheeseCamera *camera, const char *filename)
{
@@ -826,8 +874,9 @@ cheese_camera_force_stop_video_recording (gpointer data)
/**
* cheese_camera_stop_video_recording:
* @camera: a #CheeseCamera
+ *
+ * Stop recording video on the @camera.
*/
-
void
cheese_camera_stop_video_recording (CheeseCamera *camera)
{
@@ -864,9 +913,11 @@ cheese_camera_image_done_cb (GstElement *camerabin, gchar *filename,
/**
* cheese_camera_take_photo:
* @camera: a #CheeseCamera
- * @filename: name of the file to save photo to
+ * @filename: name of the file to save a photo to
*
- * Returns: TRUE on success, FALSE if an error occurred
+ * Save a photo taken with the @camera to a new file at @filename.
+ *
+ * Returns: %TRUE on success, %FALSE if an error occurred
*/
gboolean
cheese_camera_take_photo (CheeseCamera *camera, const char *filename)
@@ -911,8 +962,9 @@ cheese_camera_take_photo (CheeseCamera *camera, const char *filename)
/**
* cheese_camera_take_photo_pixbuf:
* @camera: a #CheeseCamera
+ *
+ * Returns: %TRUE if the photo was successfully captured, %FALSE otherwise
*/
-
gboolean
cheese_camera_take_photo_pixbuf (CheeseCamera *camera)
{
@@ -1044,6 +1096,12 @@ cheese_camera_class_init (CheeseCameraClass *klass)
object_class->get_property = cheese_camera_get_property;
object_class->set_property = cheese_camera_set_property;
+ /**
+ * CheeseCamera::photo-saved:
+ * @camera: a #CheeseCamera
+ *
+ * Emitted when a photo was saved to disk.
+ */
camera_signals[PHOTO_SAVED] = g_signal_new ("photo-saved", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseCameraClass, photo_saved),
@@ -1051,6 +1109,12 @@ cheese_camera_class_init (CheeseCameraClass *klass)
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+ /**
+ * CheeseCamera::photo-taken:
+ * @camera: a #CheeseCamera
+ *
+ * Emitted when a photo was taken.
+ */
camera_signals[PHOTO_TAKEN] = g_signal_new ("photo-taken", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseCameraClass, photo_taken),
@@ -1058,6 +1122,12 @@ cheese_camera_class_init (CheeseCameraClass *klass)
g_cclosure_marshal_VOID__OBJECT,
G_TYPE_NONE, 1, GDK_TYPE_PIXBUF);
+ /**
+ * CheeseCamera::video-saved:
+ * @camera: a #CheeseCamera
+ *
+ * Emitted when a video was saved to disk.
+ */
camera_signals[VIDEO_SAVED] = g_signal_new ("video-saved", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseCameraClass, video_saved),
@@ -1065,6 +1135,12 @@ cheese_camera_class_init (CheeseCameraClass *klass)
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
+ /**
+ * CheeseCamera::state-flags-changed:
+ * @camera: a #CheeseCamera
+ *
+ * Emitted when the state of the @camera #GstElement changed.
+ */
camera_signals[STATE_FLAGS_CHANGED] = g_signal_new ("state-flags-changed", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseCameraClass, state_flags_changed),
@@ -1073,12 +1149,22 @@ cheese_camera_class_init (CheeseCameraClass *klass)
G_TYPE_NONE, 1, G_TYPE_INT);
+ /**
+ * CheeseCamera:video-texture:
+ *
+ * The video texture for the #CheeseCamera to render into.
+ */
g_object_class_install_property (object_class, PROP_VIDEO_TEXTURE,
g_param_spec_pointer ("video-texture",
NULL,
NULL,
G_PARAM_READWRITE));
+ /**
+ * CheeseCamera:device-name:
+ *
+ * The path to the device node for the video capture device.
+ */
g_object_class_install_property (object_class, PROP_DEVICE_NAME,
g_param_spec_string ("device-name",
NULL,
@@ -1086,6 +1172,11 @@ cheese_camera_class_init (CheeseCameraClass *klass)
"",
G_PARAM_READWRITE));
+ /**
+ * CheeseCamera:format:
+ *
+ * The format of the video capture device.
+ */
g_object_class_install_property (object_class, PROP_FORMAT,
g_param_spec_boxed ("format",
NULL,
@@ -1118,7 +1209,6 @@ cheese_camera_init (CheeseCamera *camera)
* @x_resolution: the resolution width
* @y_resolution: the resolution height
*/
-
CheeseCamera *
cheese_camera_new (ClutterTexture *video_texture, char *camera_device_name,
int x_resolution, int y_resolution)
@@ -1148,8 +1238,9 @@ cheese_camera_new (ClutterTexture *video_texture, char *camera_device_name,
* cheese_camera_set_device_by_dev_file:
* @camera: a #CheeseCamera
* @file: the filename
+ *
+ * Set the active video capture device with the device node path.
*/
-
void
cheese_camera_set_device_by_dev_file (CheeseCamera *camera, const gchar *file)
{
@@ -1183,9 +1274,10 @@ cheese_camera_set_device_by_dev_udi (CheeseCamera *camera, const gchar *udi)
* cheese_camera_setup:
* @camera: a #CheeseCamera
* @id: (allow-none): the device id
- * @error: return location for a GError or NULL
+ * @error: return location for a #GError or %NULL
+ *
+ * Setup a video capture device.
*/
-
void
cheese_camera_setup (CheeseCamera *camera, const char *id, GError **error)
{
@@ -1266,9 +1358,9 @@ cheese_camera_setup (CheeseCamera *camera, const char *id, GError **error)
* cheese_camera_get_camera_devices:
* @camera: a #CheeseCamera
*
- * Returns: (element-type Cheese.CameraDevice) (transfer container): Array of #CheeseCameraDevice
+ * Returns: (element-type Cheese.CameraDevice) (transfer container): an array
+ * of #CheeseCameraDevice
*/
-
GPtrArray *
cheese_camera_get_camera_devices (CheeseCamera *camera)
{
@@ -1285,9 +1377,9 @@ cheese_camera_get_camera_devices (CheeseCamera *camera)
* cheese_camera_get_video_formats:
* @camera: a #CheeseCamera
*
- * Returns: (element-type Cheese.VideoFormat) (transfer container): List of #CheeseVideoFormat
+ * Returns: (element-type Cheese.VideoFormat) (transfer container): a #GList of
+ * #CheeseVideoFormat
*/
-
GList *
cheese_camera_get_video_formats (CheeseCamera *camera)
{
@@ -1303,6 +1395,12 @@ cheese_camera_get_video_formats (CheeseCamera *camera)
return NULL;
}
+/*
+ * cheese_camera_is_playing:
+ * @camera: a #CheeseCamera
+ *
+ * Returns: whether the #CheeseCamera is in the playing state
+ */
static gboolean
cheese_camera_is_playing (CheeseCamera *camera)
{
@@ -1318,9 +1416,10 @@ cheese_camera_is_playing (CheeseCamera *camera)
/**
* cheese_camera_set_video_format:
* @camera: a #CheeseCamera
- * format: a #CheeseVideoFormat
+ * @format: a #CheeseVideoFormat
+ *
+ * Sets a #CheeseVideoFormat on a #CheeseCamera.
*/
-
void
cheese_camera_set_video_format (CheeseCamera *camera, CheeseVideoFormat *format)
{
@@ -1347,9 +1446,8 @@ cheese_camera_set_video_format (CheeseCamera *camera, CheeseVideoFormat *format)
* cheese_camera_get_current_video_format:
* @camera: a #CheeseCamera
*
- * Returns: (transfer none): a #CheeseVideoFormat
+ * Returns: (transfer none): the #CheeseVideoFormat set on the #CheeseCamera
*/
-
const CheeseVideoFormat *
cheese_camera_get_current_video_format (CheeseCamera *camera)
{
@@ -1364,11 +1462,12 @@ cheese_camera_get_current_video_format (CheeseCamera *camera)
* cheese_camera_get_balance_property_range:
* @camera: a #CheeseCamera
* @property: name of the balance property
- * @min: (out): minimun value
+ * @min: (out): minimum value
* @max: (out): maximum value
* @def: (out): default value
+ *
+ * Returns: %TRUE if the operation was successful, %FALSE otherwise
*/
-
gboolean
cheese_camera_get_balance_property_range (CheeseCamera *camera,
const gchar *property,
@@ -1405,7 +1504,6 @@ cheese_camera_get_balance_property_range (CheeseCamera *camera,
* @property: name of the balance property
* @value: value to be set
*/
-
void
cheese_camera_set_balance_property (CheeseCamera *camera, const gchar *property, gdouble value)
{
diff --git a/libcheese/cheese-camera.h b/libcheese/cheese-camera.h
index 1b86428..d55eb3f 100644
--- a/libcheese/cheese-camera.h
+++ b/libcheese/cheese-camera.h
@@ -40,26 +40,56 @@ G_BEGIN_DECLS
#define CHEESE_IS_CAMERA_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), CHEESE_TYPE_CAMERA))
#define CHEESE_CAMERA_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), CHEESE_TYPE_CAMERA, CheeseCameraClass))
-typedef struct
-{
- GObject parent;
-} CheeseCamera;
+typedef struct _CheeseCameraClass CheeseCameraClass;
+typedef struct _CheeseCamera CheeseCamera;
-typedef struct
+/**
+ * CheeseCameraClass:
+ * @photo_saved: invoked when a photo was saved to disk
+ * @photo_taken: invoked when a photo was taken
+ * @video_saved: invoked when a video was saved to disk
+ * @state_flags_changed: invoked when the state of the camera #GstElement
+ * changed
+ */
+struct _CheeseCameraClass
{
+ /*< private >*/
GObjectClass parent_class;
+
+ /*< public >*/
void (*photo_saved)(CheeseCamera *camera);
void (*photo_taken)(CheeseCamera *camera, GdkPixbuf *pixbuf);
void (*video_saved)(CheeseCamera *camera);
void (*state_flags_changed)(CheeseCamera *camera, GstState new_state);
-} CheeseCameraClass;
+};
+
+/**
+ * CheeseCamera:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseCamera
+{
+ /*< private >*/
+ GObject parent;
+};
-enum CheeseCameraError
+/**
+ * CheeseCameraError:
+ * @CHEESE_CAMERA_ERROR_UNKNOWN: unknown error
+ * @CHEESE_CAMERA_ERROR_ELEMENT_NOT_FOUND: a required GStreamer element was not
+ * found
+ * @CHEESE_CAMERA_ERROR_NO_DEVICE: a #CheeseCameraDevice was not found
+ *
+ * Errors that can occur during camera setup, when calling
+ * cheese_camera_setup().
+ */
+typedef enum
{
CHEESE_CAMERA_ERROR_UNKNOWN,
CHEESE_CAMERA_ERROR_ELEMENT_NOT_FOUND,
CHEESE_CAMERA_ERROR_NO_DEVICE
-};
+} CheeseCameraError;
GType cheese_camera_get_type (void);
CheeseCamera *cheese_camera_new (ClutterTexture *video_texture,
diff --git a/libcheese/cheese-fileutil.c b/libcheese/cheese-fileutil.c
index 27b84d5..d2b06e7 100644
--- a/libcheese/cheese-fileutil.c
+++ b/libcheese/cheese-fileutil.c
@@ -29,6 +29,16 @@
#include "cheese-fileutil.h"
+/**
+ * SECTION:cheese-file-util
+ * @short_description: File utility functions for Cheese
+ * @stability: Unstable
+ * @include: cheese/cheese-fileutil.h
+ *
+ * #CheeseFileUtil provides some helpful utility functions for looking up paths
+ * for photos and videos.
+ */
+
G_DEFINE_TYPE (CheeseFileUtil, cheese_fileutil, G_TYPE_OBJECT)
#define CHEESE_FILEUTIL_GET_PRIVATE(o) \
@@ -42,6 +52,12 @@ typedef struct
gchar *burst_raw_name;
} CheeseFileUtilPrivate;
+/**
+ * cheese_fileutil_get_video_path:
+ * @fileutil: a #CheeseFileUtil
+ *
+ * Returns: (transfer none): the Cheese video path
+ */
const gchar *
cheese_fileutil_get_video_path (CheeseFileUtil *fileutil)
{
@@ -50,6 +66,12 @@ cheese_fileutil_get_video_path (CheeseFileUtil *fileutil)
return priv->video_path;
}
+/**
+ * cheese_fileutil_get_photo_path:
+ * @fileutil: a #CheeseFileUtil
+ *
+ * Returns: (transfer none): the Cheese photo path
+ */
const gchar *
cheese_fileutil_get_photo_path (CheeseFileUtil *fileutil)
{
@@ -58,12 +80,30 @@ cheese_fileutil_get_photo_path (CheeseFileUtil *fileutil)
return priv->photo_path;
}
+/**
+ * cheese_fileutil_get_path_before_224:
+ * @fileutil: a #CheeseFileUtil
+ *
+ * Returns: (transfer full): the photo path for Cheese versions before 2.24
+ */
gchar *
cheese_fileutil_get_path_before_224 (CheeseFileUtil *fileutil)
{
return g_strjoin (G_DIR_SEPARATOR_S, g_get_home_dir (), ".gnome2", "cheese", "media", NULL);
}
+/**
+ * cheese_fileutil_get_new_media_filename:
+ * @fileutil: a #CheeseFileUtil
+ * @mode: the type of media to create a filename for
+ *
+ * Creates a filename for one of the three media typed: photo, photo burst or
+ * video. If a filename for a photo burst image was previously created, this
+ * function increments the burst count automatically. To start a new burst,
+ * first call cheese_fileutil_reset_burst().
+ *
+ * Returns: (transfer full): a new filename
+ */
gchar *
cheese_fileutil_get_new_media_filename (CheeseFileUtil *fileutil, CheeseMediaMode mode)
{
@@ -130,6 +170,14 @@ cheese_fileutil_get_new_media_filename (CheeseFileUtil *fileutil, CheeseMediaMod
return filename;
}
+/**
+ * cheese_fileutil_reset_burst:
+ * @fileutil: a #CheeseFileUtil
+ *
+ * Resets the burst counter, so that calling
+ * cheese_fileutil_get_new_media_filename() with a photo burst starts a new
+ * burst of photos.
+ */
void
cheese_fileutil_reset_burst (CheeseFileUtil *fileutil)
{
@@ -204,6 +252,11 @@ cheese_fileutil_init (CheeseFileUtil *fileutil)
g_object_unref (settings);
}
+/**
+ * cheese_fileutil_new:
+ *
+ * Returns: a new #CheeseFileUtil
+ */
CheeseFileUtil *
cheese_fileutil_new ()
{
diff --git a/libcheese/cheese-fileutil.h b/libcheese/cheese-fileutil.h
index a15f75d..d795f2e 100644
--- a/libcheese/cheese-fileutil.h
+++ b/libcheese/cheese-fileutil.h
@@ -24,7 +24,18 @@
#include <glib-object.h>
+/**
+ * CHEESE_PHOTO_NAME_SUFFIX:
+ *
+ * The filename suffix for photos saved by Cheese.
+ */
#define CHEESE_PHOTO_NAME_SUFFIX ".jpg"
+
+/**
+ * CHEESE_PHOTO_VIDEO_NAME_SUFFIX:
+ *
+ * the filename suffix for videos saved by Cheese.
+ */
#define CHEESE_VIDEO_NAME_SUFFIX ".ogv"
G_BEGIN_DECLS
@@ -36,16 +47,39 @@ G_BEGIN_DECLS
#define CHEESE_IS_FILEUTIL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), CHEESE_TYPE_FILEUTIL))
#define CHEESE_FILEUTIL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), CHEESE_TYPE_FILEUTIL, CheeseFileUtilClass))
-typedef struct
-{
- GObject parent;
-} CheeseFileUtil;
+typedef struct _CheeseFileUtilClass CheeseFileUtilClass;
+typedef struct _CheeseFileUtil CheeseFileUtil;
-typedef struct
+/**
+ * CheeseFileUtilClass:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseFileUtilClass
{
+ /*< private >*/
GObjectClass parent_class;
-} CheeseFileUtilClass;
+};
+
+/**
+ * CheeseFileUtil:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseFileUtil
+{
+ /*< private >*/
+ GObject parent;
+};
+/**
+ * CheeseMediaMode:
+ * @CHEESE_MEDIA_MODE_PHOTO: photo
+ * @CHEESE_MEDIA_MODE_VIDEO: video
+ * @CHEESE_MEDIA_MODE_BURST: a burst of photos
+ *
+ * The media type.
+ */
typedef enum
{
CHEESE_MEDIA_MODE_PHOTO,
diff --git a/libcheese/cheese-flash.c b/libcheese/cheese-flash.c
index 7bff521..e14e300 100644
--- a/libcheese/cheese-flash.c
+++ b/libcheese/cheese-flash.c
@@ -19,12 +19,9 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* This is a "flash" object that you can create and invoke a method "flash" on to
- * flood the screen with white temporarily */
-
#include <gtk/gtk.h>
-#include <cheese-camera.h>
+#include "cheese-camera.h"
#include "cheese-flash.h"
#ifdef GDK_WINDOWING_X11
@@ -35,6 +32,16 @@
#include <gdk/gdkx.h>
#endif /* GDK_WINDOWING_X11 */
+/**
+ * SECTION:cheese-flash
+ * @short_description: Flash the screen, like a real camera flash
+ * @stability: Unstable
+ * @include: cheese/cheese-flash.h
+ *
+ * #CheeseFlash is an object that you can create and invoke a method "flash" on
+ * to temporarily flood the screen with white.
+ */
+
enum
{
PROP_0,
@@ -271,6 +278,12 @@ cheese_flash_class_init (CheeseFlashClass *klass)
object_class->dispose = cheese_flash_dispose;
object_class->finalize = cheese_flash_finalize;
+ /**
+ * CheeseFlash:parent:
+ *
+ * Parent #GtkWidget for the #CheeseFlash. The flash will be fired on the
+ * screen where the parent widget is shown.
+ */
g_object_class_install_property (object_class, PROP_PARENT,
g_param_spec_object ("parent",
NULL,
@@ -318,6 +331,12 @@ cheese_flash_start_fade (gpointer data)
return FALSE;
}
+/**
+ * cheese_flash_fire:
+ * @flash: a #CheeseFlash
+ *
+ * Fire the flash.
+ */
void
cheese_flash_fire (CheeseFlash *flash)
{
@@ -358,6 +377,12 @@ cheese_flash_fire (CheeseFlash *flash)
flash_priv->flash_timeout_tag = g_timeout_add (FLASH_DURATION, cheese_flash_start_fade, (gpointer) flash);
}
+/**
+ * cheese_flash_new:
+ * @parent: a parent #GtkWidget
+ *
+ * Returns: a new #CheeseFlash
+ */
CheeseFlash *
cheese_flash_new (GtkWidget *parent)
{
diff --git a/libcheese/cheese-flash.h b/libcheese/cheese-flash.h
index 3571729..8c46d85 100644
--- a/libcheese/cheese-flash.h
+++ b/libcheese/cheese-flash.h
@@ -31,15 +31,30 @@ G_BEGIN_DECLS
#define CHEESE_IS_FLASH_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), CHEESE_TYPE_FLASH))
#define CHEESE_FLASH_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), CHEESE_TYPE_FLASH, CheeseFlashClass))
-typedef struct
+typedef struct _CheeseFlashClass CheeseFlashClass;
+typedef struct _CheeseFlash CheeseFlash;
+
+/**
+ * CheeseFlashClass:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseFlashClass
{
+ /*< private >*/
GObjectClass parent_class;
-} CheeseFlashClass;
+};
-typedef struct
+/**
+ * CheeseFlash:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseFlash
{
+ /*< private >*/
GObject parent_instance;
-} CheeseFlash;
+};
GType cheese_flash_get_type (void) G_GNUC_CONST;
CheeseFlash *cheese_flash_new (GtkWidget *parent);
diff --git a/libcheese/cheese-widget.c b/libcheese/cheese-widget.c
index c75cae3..fd876c8 100644
--- a/libcheese/cheese-widget.c
+++ b/libcheese/cheese-widget.c
@@ -24,13 +24,14 @@
#include <mx/mx.h>
#include "cheese-widget.h"
+#include "cheese-widget-private.h"
#include "cheese-camera.h"
#include "cheese-enums.h"
#include "cheese-aspect-frame.h"
/**
* SECTION:cheese-widget
- * @short_description: A photo/video capture widget.
+ * @short_description: A photo/video capture widget
* @stability: Unstable
* @include: cheese/cheese-widget.h
*
@@ -51,13 +52,6 @@ enum
PROP_STATE
};
-enum
-{
- SPINNER_PAGE = 0,
- WEBCAM_PAGE = 1,
- PROBLEM_PAGE = 2,
-};
-
typedef struct
{
GtkWidget *spinner;
@@ -429,8 +423,8 @@ cheese_widget_class_init (CheeseWidgetClass *klass)
* clutter_gst_init(), and check for errors during initialization, before
* calling this function.
*
- * Return value: a #CheeseWidget widget.
- **/
+ * Returns: a new #CheeseWidget
+ */
GtkWidget *
cheese_widget_new (void)
{
@@ -449,6 +443,12 @@ cheese_widget_get_settings (CheeseWidget *widget)
return priv->settings;
}
+/**
+ * cheese_widget_get_camera:
+ * @widget: a #CheeseWidget
+ *
+ * Returns: a #CheeseCamera for this #CheeseWidget
+ */
GObject *
cheese_widget_get_camera (CheeseWidget *widget)
{
@@ -461,6 +461,12 @@ cheese_widget_get_camera (CheeseWidget *widget)
return G_OBJECT (priv->webcam);
}
+/**
+ * cheese_widget_get_video_area:
+ * @widget: a #CheeseWidget
+ *
+ * Returns: a #GtkClutterEmbed of the stream from the video capture device
+ */
GtkWidget *
cheese_widget_get_video_area (CheeseWidget *widget)
{
@@ -478,7 +484,8 @@ cheese_widget_get_video_area (CheeseWidget *widget)
* @widget: a #CheeseWidget
* @error: return location for the error
*
- * Listen for notify::state signals and call this when the current state is %CHEESE_WIDGET_STATE_ERROR.
+ * Listen for notify::state signals and call this when the current state is
+ * %CHEESE_WIDGET_STATE_ERROR.
*
* The returned #GError will contain more details on what went wrong.
**/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
