AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-26 05:31:07 +00:00
Code Issues Projects Releases Wiki Activity

Add docs

Browse Source
This commit is contained in:
Matthias Clasen 2012-02-03 19:40:36 -05:00
parent 03a2b338ee
commit 23a5f7a22c
8 changed files with 248 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/reference/gtk/gtk-docs.sgml
View File

@ -210,6 +210,9 @@
<chapter id="SelectorWidgets">
<title>Selectors (Color/File/Font)</title>
<xi:include href="xml/gtkcolorbutton.xml" />
<xi:include href="xml/gtkcolorchooser.xml" />
<xi:include href="xml/gtkcolorchooserwidget.xml" />
<xi:include href="xml/gtkcolorchooserdialog.xml" />
<xi:include href="xml/gtkcolorseldlg.xml" />
<xi:include href="xml/gtkcolorsel.xml" />
<xi:include href="xml/gtkhsv.xml" />
@ -220,7 +223,8 @@
<xi:include href="xml/gtkfilefilter.xml" />
<xi:include href="xml/gtkfontbutton.xml" />
<xi:include href="xml/gtkfontchooser.xml" />
<xi:include href="xml/gtkfontchooserdlg.xml" />
<xi:include href="xml/gtkfontchooserwidget.xml" />
<xi:include href="xml/gtkfontchooserdialog.xml" />
<xi:include href="xml/gtkfontsel.xml" />
<xi:include href="xml/gtkfontseldlg.xml" />
</chapter>

59
docs/reference/gtk/gtk3-sections.txt
View File

@ -1535,7 +1535,7 @@ gtk_font_chooser_widget_get_type
</SECTION>
<SECTION>
<FILE>gtkfontchooserdlg</FILE>
<FILE>gtkfontchooserdialog</FILE>
<TITLE>GtkFontChooserDialog</TITLE>
GtkFontChooserDialog
gtk_font_chooser_dialog_new
@ -7298,3 +7298,60 @@ GtkOverlayClass
gtk_overlay_get_type
GtkOverlayPrivate
</SECTION>
<SECTION>
<FILE>gtkcolorchooser</FILE>
<TITLE>GtkColorChooser</TITLE>
GtkColorChooser
gtk_color_chooser_get_rgba
gtk_color_chooser_set_rgba
gtk_color_chooser_get_use_alpha
gtk_color_chooser_set_use_alpha
<SUBSECTION Standard>
GTK_TYPE_COLOR_CHOOSER
GTK_COLOR_CHOOSER
GTK_IS_COLOR_CHOOSER
GTK_COLOR_CHOOSER_GET_IFACE
<SUBSECTION Private>
gtk_color_chooser_get_type
</SECTION>
<SECTION>
<FILE>gtkcolorchooserwidget</FILE>
<TITLE>GtkColorChooserWidget</TITLE>
GtkColorChooserWidget
gtk_color_chooser_widget_new
<SUBSECTION Standard>
GTK_TYPE_COLOR_CHOOSER_WIDGET
GTK_COLOR_CHOOSER_WIDGET
GTK_COLOR_CHOOSER_WIDGET_CLASS
GTK_IS_COLOR_CHOOSER_WIDGET
GTK_IS_COLOR_CHOOSER_WIDGET_CLASS
GTK_COLOR_CHOOSER_WIDGET_GET_CLASS
<SUBSECTION Private>
gtk_color_chooser_widget_get_type
GtkColorChooserWidgetPrivate
</SECTION>
<SECTION>
<FILE>gtkcolorchooserdialog</FILE>
<TITLE>GtkColorChooserDialog</TITLE>
GtkColorChooserDialog
gtk_color_chooser_dialog_new
<SUBSECTION Standard>
GTK_TYPE_COLOR_CHOOSER_DIALOG
GTK_COLOR_CHOOSER_DIALOG
GTK_COLOR_CHOOSER_DIALOG_CLASS
GTK_IS_COLOR_CHOOSER_DIALOG
GTK_IS_COLOR_CHOOSER_DIALOG_CLASS
GTK_COLOR_CHOOSER_DIALOG_GET_CLASS
<SUBSECTION Private>
GtkColorChooserDialogPrivate
gtk_color_chooser_dialog_get_type
</SECTION>

3
docs/reference/gtk/gtk3.types
View File

@ -47,6 +47,9 @@ gtk_check_button_get_type
gtk_check_menu_item_get_type
gtk_clipboard_get_type
gtk_color_button_get_type
gtk_color_chooser_get_type
gtk_color_chooser_dialog_get_type
gtk_color_chooser_widget_get_type
gtk_color_selection_dialog_get_type
gtk_color_selection_get_type
gtk_combo_box_get_type

23
gtk/gtkcolorbutton.c
View File

@ -164,9 +164,9 @@ gtk_color_button_class_init (GtkColorButtonClass *klass)
/**
* GtkColorButton:use-alpha:
*
* If this property is set to %TRUE, the color swatch on the button is rendered against a
* checkerboard background to show its opacity and the opacity slider is displayed in the
* color selection dialog.
* If this property is set to %TRUE, the color swatch on the button is
* rendered against a checkerboard background to show its opacity and
* the opacity slider is displayed in the color selection dialog.
*
* Since: 2.4
*/
@ -489,7 +489,6 @@ gtk_color_button_init (GtkColorButton *button)
button->priv->title = g_strdup (_("Pick a Color")); /* default title */
/* Start with opaque black, alpha disabled */
button->priv->rgba.red = 0;
button->priv->rgba.green = 0;
button->priv->rgba.blue = 0;
@ -671,7 +670,7 @@ gtk_color_button_clicked (GtkButton *b)
*
* Since: 2.4
*
* Deprecated: Use gtk_color_button_set_rgba() instead.
* Deprecated: Use gtk_color_chooser_set_rgba() instead.
*/
void
gtk_color_button_set_color (GtkColorButton *button,
@ -699,6 +698,8 @@ gtk_color_button_set_color (GtkColorButton *button,
* Sets the current opacity to be @alpha.
*
* Since: 2.4
*
* Deprecated: 3.4: Use gtk_color_chooser_set_rgba() instead.
*/
void
gtk_color_button_set_alpha (GtkColorButton *button,
@ -723,7 +724,7 @@ gtk_color_button_set_alpha (GtkColorButton *button,
*
* Since: 2.4
*
* Deprecated: 3.4: Use gtk_color_button_get_rgba() instead.
* Deprecated: 3.4: Use gtk_color_chooser_get_rgba() instead.
*/
void
gtk_color_button_get_color (GtkColorButton *button,
@ -745,6 +746,8 @@ gtk_color_button_get_color (GtkColorButton *button,
* Return value: an integer between 0 and 65535
*
* Since: 2.4
*
* Deprecated: 3.4: Use gtk_color_chooser_get_rgba() instead.
*/
guint16
gtk_color_button_get_alpha (GtkColorButton *button)
@ -762,6 +765,8 @@ gtk_color_button_get_alpha (GtkColorButton *button)
* Sets the current color to be @rgba.
*
* Since: 3.0
*
* Deprecated: 3.4: Use gtk_color_chooser_set_rgba() instead.
*/
void
gtk_color_button_set_rgba (GtkColorButton *button,
@ -786,6 +791,8 @@ gtk_color_button_set_rgba (GtkColorButton *button,
* Sets @rgba to be the current color in the #GtkColorButton widget.
*
* Since: 3.0
*
* Deprecated: 3.4: Use gtk_color_chooser_get_rgba() instead.
*/
void
gtk_color_button_get_rgba (GtkColorButton *button,
@ -805,6 +812,8 @@ gtk_color_button_get_rgba (GtkColorButton *button,
* Sets whether or not the color button should use the alpha channel.
*
* Since: 2.4
*
* Deprecated: 3.4: Use gtk_color_chooser_set_use_alpha() instead.
*/
void
gtk_color_button_set_use_alpha (GtkColorButton *button,
@ -833,6 +842,8 @@ gtk_color_button_set_use_alpha (GtkColorButton *button,
* Returns: %TRUE if the color sample uses alpha channel, %FALSE if not
*
* Since: 2.4
*
* Deprecated: 3.4: Use gtk_color_chooser_get_use_alpha() instead.
*/
gboolean
gtk_color_button_get_use_alpha (GtkColorButton *button)

70
gtk/gtkcolorchooser.c
View File

@ -26,6 +26,22 @@
#include "gtktypebuiltins.h"
#include "gtkprivate.h"
/**
* SECTION:gtkcolorchooser
* @Short_description: Interface implemented by widgets for choosing colors
* @Title: GtkColorChooser
* @See_also: #GtkColorChooserDialog, #GtkColorChooserWidget, #GtkColorButton
*
* #GtkColorChooser is an interface that is implemented by widgets
* for choosing colors. Depending on the situation, colors may be
* allowed to have alpha (translucency).
*
* In GTK+, the main widgets that implement this interface are
* #GtkColorChooserWidget, #GtkColorChooserDialog and #GtkColorButton.
*
* Since: 3.4
*/
enum
{
COLOR_ACTIVATED,
@ -39,6 +55,15 @@ G_DEFINE_INTERFACE (GtkColorChooser, gtk_color_chooser, G_TYPE_OBJECT);
static void
gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
{
/**
* GtkColorChooser:rgba:
*
* The ::rgba property contains the currently selected color,
* as a #GdkRGBA struct. The property can be set to change
* the current selection programmatically.
*
* Since: 3.4
*/
g_object_interface_install_property (iface,
g_param_spec_boxed ("rgba",
P_("Color"),
@ -46,6 +71,19 @@ gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
GDK_TYPE_RGBA,
GTK_PARAM_READWRITE));
/**
* GtkColorChooser:use-alpha:
*
* When ::use-alpha is %TRUE, colors may have alpha (translucency)
* information. When it is %FALSE, the #GdkRGBA struct obtained
* via the #GtkColorChooser:rgba property will be forced to have
* alpha == 1.
*
* Implementations are expected to show alpha by rendering the color
* over a non-uniform background (like a checkerboard pattern).
*
* Since: 3.4
*/
g_object_interface_install_property (iface,
g_param_spec_boolean ("use-alpha",
P_("Use alpha"),
@ -55,14 +93,16 @@ gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
/**
* GtkColorChooser::color-activated:
* @self: the object which received the signal
* @chooser: the object which received the signal
* @color: the color
*
* Emitted when a color is activated from the color chooser.
* This usually happens when the user clicks a color swatch,
* or a color is selected and the user presses one of the keys
* Space, Shift+Space, Return or Enter.
*/
*
* Since: 3.4
*/
signals[COLOR_ACTIVATED] =
g_signal_new ("color-activated",
GTK_TYPE_COLOR_CHOOSER,
@ -80,6 +120,8 @@ gtk_color_chooser_default_init (GtkColorChooserInterface *iface)
* @color: return location for the color
*
* Gets the currently-selected color.
*
* Since: 3.4
*/
void
gtk_color_chooser_get_rgba (GtkColorChooser *chooser,
@ -95,7 +137,7 @@ gtk_color_chooser_get_rgba (GtkColorChooser *chooser,
* @chooser: a #GtkColorChooser
* @color: the new color
*
* Sets the currently-selected color.
* Sets the color.
*/
void
gtk_color_chooser_set_rgba (GtkColorChooser *chooser,
@ -111,11 +153,20 @@ void
_gtk_color_chooser_color_activated (GtkColorChooser *chooser,
const GdkRGBA *color)
{
g_return_if_fail (GTK_IS_COLOR_CHOOSER (chooser));
g_signal_emit (chooser, signals[COLOR_ACTIVATED], 0, color);
}
/**
* gtk_color_chooser_get_use_alpha:
* @chooser: a #GtkColorChooser
*
* Returns whether the color chooser shows the alpha channel.
*
* Returns: %TRUE if the color chooser uses the alpha channel,
* %FALSE if not
*
* Since: 3.4
*/
gboolean
gtk_color_chooser_get_use_alpha (GtkColorChooser *chooser)
{
@ -128,6 +179,15 @@ gtk_color_chooser_get_use_alpha (GtkColorChooser *chooser)
return use_alpha;
}
/**
* gtk_color_chooser_set_use_alpha:
* @chooser: a #GtkColorChooser
* @use_alpha: %TRUE if color chooser should use alpha channel, %FALSE if not
*
* Sets whether or not the color chooser should use the alpha channel.
*
* Since: 3.4
*/
void
gtk_color_chooser_set_use_alpha (GtkColorChooser *chooser,
gboolean use_alpha)

2
gtk/gtkcolorchooser.h
View File

@ -63,7 +63,7 @@ void gtk_color_chooser_set_rgba (GtkColorChooser *chooser,
const GdkRGBA *color);
gboolean gtk_color_chooser_get_use_alpha (GtkColorChooser *chooser);
void gtk_color_chooser_set_use_alpha (GtkColorChooser *chooser,
gboolean show_alpha);
gboolean use_alpha);
G_END_DECLS

88
gtk/gtkcolorchooserdialog.c
View File

@ -29,10 +29,21 @@
#include "gtkcolorchooserdialog.h"
#include "gtkcolorchooserwidget.h"
/**
* SECTION:gtkcolorchooserdialog
* @Short_description: A dialog for choosing colors
* @Title: GtkColorChooserDialog
* @See_also: #GtkColorChooser, #GtkDialog
*
* The #GtkColorChooserDialog widget is a dialog for choosing
* a color. It implements the #GtkColorChooser interface.
*
* Since: 3.4
*/
struct _GtkColorChooserDialogPrivate
{
GtkWidget *color_chooser;
GtkWidget *chooser;
GtkWidget *select_button;
GtkWidget *cancel_button;
@ -41,8 +52,8 @@ struct _GtkColorChooserDialogPrivate
enum
{
PROP_ZERO,
PROP_COLOR,
PROP_SHOW_ALPHA,
PROP_RGBA,
PROP_USE_ALPHA,
PROP_SHOW_EDITOR
};
@ -57,7 +68,7 @@ propagate_notify (GObject *o,
GParamSpec *pspec,
GtkColorChooserDialog *cc)
{
g_object_notify (G_OBJECT (cc), "color");
g_object_notify (G_OBJECT (cc), "rgba");
}
static void
@ -93,16 +104,16 @@ gtk_color_chooser_dialog_init (GtkColorChooserDialog *cc)
gtk_window_set_resizable (GTK_WINDOW (cc), FALSE);
/* Create the content area */
priv->color_chooser = gtk_color_chooser_widget_new ();
gtk_container_set_border_width (GTK_CONTAINER (priv->color_chooser), 5);
gtk_widget_show (priv->color_chooser);
priv->chooser = gtk_color_chooser_widget_new ();
gtk_container_set_border_width (GTK_CONTAINER (priv->chooser), 5);
gtk_widget_show (priv->chooser);
gtk_box_pack_start (GTK_BOX (content_area),
priv->color_chooser, TRUE, TRUE, 0);
priv->chooser, TRUE, TRUE, 0);
g_signal_connect (priv->color_chooser, "notify::color",
g_signal_connect (priv->chooser, "notify::rgba",
G_CALLBACK (propagate_notify), cc);
g_signal_connect (priv->color_chooser, "color-activated",
g_signal_connect (priv->chooser, "color-activated",
G_CALLBACK (color_activated_cb), cc);
/* Create the action area */
@ -132,11 +143,11 @@ gtk_color_chooser_dialog_response (GtkDialog *dialog,
{
GdkRGBA color;
gtk_color_chooser_get_color (GTK_COLOR_CHOOSER (dialog), &color);
gtk_color_chooser_set_color (GTK_COLOR_CHOOSER (dialog), &color);
gtk_color_chooser_get_rgba (GTK_COLOR_CHOOSER (dialog), &color);
gtk_color_chooser_set_rgba (GTK_COLOR_CHOOSER (dialog), &color);
}
g_object_set (GTK_COLOR_CHOOSER_DIALOG (dialog)->priv->color_chooser,
g_object_set (GTK_COLOR_CHOOSER_DIALOG (dialog)->priv->chooser,
"show-editor", FALSE, NULL);
}
@ -151,21 +162,21 @@ gtk_color_chooser_dialog_get_property (GObject *object,
switch (prop_id)
{
case PROP_COLOR:
case PROP_RGBA:
{
GdkRGBA color;
gtk_color_chooser_get_color (cc, &color);
gtk_color_chooser_get_rgba (cc, &color);
g_value_set_boxed (value, &color);
}
break;
case PROP_SHOW_ALPHA:
g_value_set_boolean (value, gtk_color_chooser_get_show_alpha (GTK_COLOR_CHOOSER (cd->priv->color_chooser)));
case PROP_USE_ALPHA:
g_value_set_boolean (value, gtk_color_chooser_get_use_alpha (GTK_COLOR_CHOOSER (cd->priv->chooser)));
break;
case PROP_SHOW_EDITOR:
{
gboolean show_editor;
g_object_get (cd->priv->color_chooser, "show-editor", &show_editor, NULL);
g_object_get (cd->priv->chooser, "show-editor", &show_editor, NULL);
g_value_set_boolean (value, show_editor);
}
break;
@ -186,14 +197,14 @@ gtk_color_chooser_dialog_set_property (GObject *object,
switch (prop_id)
{
case PROP_COLOR:
gtk_color_chooser_set_color (cc, g_value_get_boxed (value));
case PROP_RGBA:
gtk_color_chooser_set_rgba (cc, g_value_get_boxed (value));
break;
case PROP_SHOW_ALPHA:
gtk_color_chooser_set_show_alpha (GTK_COLOR_CHOOSER (cd->priv->color_chooser), g_value_get_boolean (value));
case PROP_USE_ALPHA:
gtk_color_chooser_set_use_alpha (GTK_COLOR_CHOOSER (cd->priv->chooser), g_value_get_boolean (value));
break;
case PROP_SHOW_EDITOR:
g_object_set (cd->priv->color_chooser,
g_object_set (cd->priv->chooser,
"show-editor", g_value_get_boolean (value),
NULL);
break;
@ -214,8 +225,8 @@ gtk_color_chooser_dialog_class_init (GtkColorChooserDialogClass *class)
dialog_class->response = gtk_color_chooser_dialog_response;
g_object_class_override_property (object_class, PROP_COLOR, "color");
g_object_class_override_property (object_class, PROP_SHOW_ALPHA, "show-alpha");
g_object_class_override_property (object_class, PROP_RGBA, "rgba");
g_object_class_override_property (object_class, PROP_USE_ALPHA, "use-alpha");
g_object_class_install_property (object_class, PROP_SHOW_EDITOR,
g_param_spec_boolean ("show-editor", P_("Show editor"), P_("Show editor"),
FALSE, GTK_PARAM_READWRITE));
@ -225,30 +236,41 @@ gtk_color_chooser_dialog_class_init (GtkColorChooserDialogClass *class)
}
static void
gtk_color_chooser_dialog_get_color (GtkColorChooser *chooser,
GdkRGBA *color)
gtk_color_chooser_dialog_get_rgba (GtkColorChooser *chooser,
GdkRGBA *color)
{
GtkColorChooserDialog *cc = GTK_COLOR_CHOOSER_DIALOG (chooser);
gtk_color_chooser_get_color (GTK_COLOR_CHOOSER (cc->priv->color_chooser), color);
gtk_color_chooser_get_rgba (GTK_COLOR_CHOOSER (cc->priv->chooser), color);
}
static void
gtk_color_chooser_dialog_set_color (GtkColorChooser *chooser,
const GdkRGBA *color)
gtk_color_chooser_dialog_set_rgba (GtkColorChooser *chooser,
const GdkRGBA *color)
{
GtkColorChooserDialog *cc = GTK_COLOR_CHOOSER_DIALOG (chooser);
gtk_color_chooser_set_color (GTK_COLOR_CHOOSER (cc->priv->color_chooser), color);
gtk_color_chooser_set_rgba (GTK_COLOR_CHOOSER (cc->priv->chooser), color);
}
static void
gtk_color_chooser_dialog_iface_init (GtkColorChooserInterface *iface)
{
iface->get_color = gtk_color_chooser_dialog_get_color;
iface->set_color = gtk_color_chooser_dialog_set_color;
iface->get_rgba = gtk_color_chooser_dialog_get_rgba;
iface->set_rgba = gtk_color_chooser_dialog_set_rgba;
}
/**
* gtk_color_chooser_dialog_new:
* @title: (allow-none): Title of the dialog, or %NULL
* @parent: (allow-none): Transient parent of the dialog, or %NULL
*
* Creates a new #GtkColorChooserDialog.
*
* Return value: a new #GtkColorChooserDialog
*
* Since: 3.4
*/
GtkWidget *
gtk_color_chooser_dialog_new (const gchar *title,
GtkWindow *parent)

44
gtk/gtkcolorchooserwidget.c
View File

@ -34,6 +34,32 @@
#include "gtksizegroup.h"
#include "gtkalignment.h"
/**
* SECTION:gtkcolorchooserwidget
* @Short_description: A widget for choosing colors
* @Title: GtkColorChooserWidget
* @See_also: #GtkColorChooserDialog
*
* The #GtkColorChooserWidget widget lets the user select a
* color. By default, the chooser presents a prefined palette
* of colors, plus a small number of settable custom colors.
* It is also possible to select a different color with the
* single-color editor. To enter the single-color editing mode,
* use the context menu of any color of the palette, or use the
* '+' button to add a new custom color.
*
* The chooser automatically remembers the last selection, as well
* as custom colors.
*
* To change the initially selected color, use gtk_color_chooser_set_rgba().
* To get the selected font use gtk_color_chooser_get_rgba().
*
* The #GtkColorChooserWidget is used in the #GtkColorChooserDialog
* to provide a dialog for selecting colors.
*
* Since: 3.4
*/
struct _GtkColorChooserWidgetPrivate
{
GtkWidget *palette;
@ -472,6 +498,15 @@ gtk_color_chooser_widget_class_init (GtkColorChooserWidgetClass *class)
g_object_class_override_property (object_class, PROP_RGBA, "rgba");
g_object_class_override_property (object_class, PROP_USE_ALPHA, "use-alpha");
/**
* GtkColorChooserWidget:show-editor:
*
* The ::show-editor property is %TRUE when the color chooser
* is showing the single-color editor. It can be set to switch
* the color chooser into single-color editing mode.
*
* Since: 3.4
*/
g_object_class_install_property (object_class, PROP_SHOW_EDITOR,
g_param_spec_boolean ("show-editor", P_("Show editor"), P_("Show editor"),
FALSE, GTK_PARAM_READWRITE));
@ -580,6 +615,15 @@ gtk_color_chooser_widget_iface_init (GtkColorChooserInterface *iface)
iface->set_rgba = gtk_color_chooser_widget_set_rgba;
}
/**
* gtk_color_chooser_widget_new:
*
* Creates a new #GtkColorChooserWidget.
*
* Returns: a new #GtkColorChooserWidget
*
* Since: 3.4
*/
GtkWidget *
gtk_color_chooser_widget_new (void)
{