diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 63cd349c72..ce6d6e2533 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -470,7 +470,10 @@ HTML_IMAGES = \ $(srcdir)/images/getting-started-app10.png \ $(srcdir)/images/exampleapp.png \ $(srcdir)/images/flow-box.png \ - $(srcdir)/images/inspector.png + $(srcdir)/images/inspector.png \ + $(srcdir)/images/gedit-shortcuts.png \ + $(srcdir)/images/clocks-shortcuts.png \ + $(srcdir)/images/builder-shortcuts.png if ENABLE_DOC_CROSS_REFERENCES # Extra options to supply to gtkdoc-fixref diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 8f0402f6ef..3b975641be 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -239,6 +239,15 @@ + + Shortcuts Overview + + + + + + + Miscellaneous @@ -253,7 +262,6 @@ - diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index 6a4cdca031..f4482e1378 100644 --- a/docs/reference/gtk/gtk3-sections.txt +++ b/docs/reference/gtk/gtk3-sections.txt @@ -8426,6 +8426,70 @@ gtk_gl_area_get_type
gtkshortcutswindow GtkShortcutsWindow + +GTK_TYPE_SHORTCUTS_WINDOW +GTK_SHORTCUTS_WINDOW +GTK_IS_SHORTCUTS_WINDOW +GTK_SHORTCUTS_WINDOW_CLASS +GTK_IS_SHORTCUTS_WINDOW_CLASS +GTK_GET_SHORTCUTS_WINDOW_CLASS gtk_shortcuts_window_get_type
+ +
+gtkshortcutssection +GtkShortcutsSection + +GTK_TYPE_SHORTCUTS_SECTION +GTK_SHORTCUTS_SECTION +GTK_IS_SHORTCUTS_SECTION +GTK_SHORTCUTS_SECTION_CLASS +GTK_IS_SHORTCUTS_SECTION_CLASS +GTK_GET_SHORTCUTS_SECTION_CLASS + +gtk_shortcuts_section_get_type +
+ +
+gtkshortcutsgroup +GtkShortcutsGroup + +GTK_TYPE_SHORTCUTS_GROUP +GTK_SHORTCUTS_GROUP +GTK_IS_SHORTCUTS_GROUP +GTK_SHORTCUTS_GROUP_CLASS +GTK_IS_SHORTCUTS_GROUP_CLASS +GTK_GET_SHORTCUTS_GROUP_CLASS + +gtk_shortcuts_group_get_type +
+ +
+gtkshortcutsshortcut +GtkShortcutsShortcut + +GTK_TYPE_SHORTCUTS_SHORTCUT +GTK_SHORTCUTS_SHORTCUT +GTK_IS_SHORTCUTS_SHORTCUT +GTK_SHORTCUTS_SHORTCUT_CLASS +GTK_IS_SHORTCUTS_SHORTCUT_CLASS +GTK_GET_SHORTCUTS_SHORTCUT_CLASS + + +gtk_shortcuts_shortcut_get_type +
+ +
+gtkshortcutsgesture +GtkShortcutsGesture + +GTK_TYPE_SHORTCUTS_GESTURE +GTK_SHORTCUTS_GESTURE +GTK_IS_SHORTCUTS_GESTURE +GTK_SHORTCUTS_GESTURE_CLASS +GTK_IS_SHORTCUTS_GESTURE_CLASS +GTK_GET_SHORTCUTS_GESTURE_CLASS + +gtk_shortcuts_gesture_get_type +
diff --git a/docs/reference/gtk/gtk3.types.in b/docs/reference/gtk/gtk3.types.in index 4b206223e8..93e42dcc12 100644 --- a/docs/reference/gtk/gtk3.types.in +++ b/docs/reference/gtk/gtk3.types.in @@ -173,12 +173,17 @@ gtk_separator_get_type gtk_separator_menu_item_get_type gtk_separator_tool_item_get_type gtk_settings_get_type -gtk_stack_sidebar_get_type +gtk_shortcuts_window_get_type +gtk_shortcuts_section_get_type +gtk_shortcuts_group_get_type +gtk_shortcuts_shortcut_get_type +gtk_shortcuts_gesture_get_type gtk_size_group_get_type @ENABLE_ON_X11@gtk_socket_get_type gtk_spin_button_get_type gtk_spinner_get_type gtk_stack_get_type +gtk_stack_sidebar_get_type gtk_stack_switcher_get_type gtk_statusbar_get_type gtk_status_icon_get_type diff --git a/docs/reference/gtk/images/builder-shortcuts.png b/docs/reference/gtk/images/builder-shortcuts.png new file mode 100644 index 0000000000..639a1d3c37 Binary files /dev/null and b/docs/reference/gtk/images/builder-shortcuts.png differ diff --git a/docs/reference/gtk/images/clocks-shortcuts.png b/docs/reference/gtk/images/clocks-shortcuts.png new file mode 100644 index 0000000000..9ab2d5a71f Binary files /dev/null and b/docs/reference/gtk/images/clocks-shortcuts.png differ diff --git a/gtk/Makefile.am b/gtk/Makefile.am index 13ec0ddf36..45af8fbbb2 100644 --- a/gtk/Makefile.am +++ b/gtk/Makefile.am @@ -269,6 +269,10 @@ gtk_public_h_sources = \ gtkseparatormenuitem.h \ gtkseparatortoolitem.h \ gtksettings.h \ + gtkshortcutsgesture.h \ + gtkshortcutsgroup.h \ + gtkshortcutssection.h \ + gtkshortcutsshortcut.h \ gtkshortcutswindow.h \ gtkshow.h \ gtkstacksidebar.h \ @@ -507,10 +511,8 @@ gtk_private_h_sources = \ gtksidebarrowprivate.h \ gtksettingsprivate.h \ gtkshortcutsgestureprivate.h \ - gtkshortcutsgrouprivate.h \ gtkshortcutlabelprivate.h \ gtkshortcutsshortcutprivate.h \ - gtkshortcutssectionprivate.h \ gtksizegroup-private.h \ gtksizerequestcacheprivate.h \ gtksocketprivate.h \ diff --git a/gtk/gtk.h b/gtk/gtk.h index 3163d60bb2..ae556d4847 100644 --- a/gtk/gtk.h +++ b/gtk/gtk.h @@ -183,6 +183,10 @@ #include #include #include +#include +#include +#include +#include #include #include #include diff --git a/gtk/gtkshortcutsgesture.c b/gtk/gtkshortcutsgesture.c index c0c7f527cf..0889da66c8 100644 --- a/gtk/gtkshortcutsgesture.c +++ b/gtk/gtkshortcutsgesture.c @@ -18,7 +18,7 @@ #include "config.h" -#include "gtkshortcutsgestureprivate.h" +#include "gtkshortcutsgesture.h" #include "gtkimage.h" #include "gtklabel.h" #include "gtksizegroup.h" @@ -27,6 +27,16 @@ #include "gtkprivate.h" #include "gtkintl.h" +/** + * SECTION:gtkshortcutsgesture + * @Title: GtkShortcutsGesture + * @Short_description: Represents a gesture in a GtkShortcutsWindow + * + * A GtkShortcutsGesture represents a single gesture with an image + * an a short text. + * + * This widget is only meant to be used with #GtkShortcutsWindow. + */ struct _GtkShortcutsGesture { GtkBox parent_instance; @@ -34,9 +44,9 @@ struct _GtkShortcutsGesture GtkImage *image; GtkLabel *title; GtkLabel *subtitle; - GtkBox *desc_box; + GtkBox *title_box; - GtkSizeGroup *desc_size_group; + GtkSizeGroup *title_size_group; GtkSizeGroup *icon_size_group; }; @@ -49,26 +59,26 @@ G_DEFINE_TYPE (GtkShortcutsGesture, gtk_shortcuts_gesture, GTK_TYPE_BOX) enum { PROP_0, - PROP_DESC_SIZE_GROUP, PROP_ICON, - PROP_ICON_SIZE_GROUP, - PROP_SUBTITLE, PROP_TITLE, + PROP_SUBTITLE, + PROP_ICON_SIZE_GROUP, + PROP_TITLE_SIZE_GROUP, LAST_PROP }; static GParamSpec *properties[LAST_PROP]; static void -gtk_shortcuts_gesture_set_desc_size_group (GtkShortcutsGesture *self, - GtkSizeGroup *group) +gtk_shortcuts_gesture_set_title_size_group (GtkShortcutsGesture *self, + GtkSizeGroup *group) { - if (self->desc_size_group) - gtk_size_group_remove_widget (self->desc_size_group, GTK_WIDGET (self->desc_box)); + if (self->title_size_group) + gtk_size_group_remove_widget (self->title_size_group, GTK_WIDGET (self->title_box)); if (group) - gtk_size_group_add_widget (group, GTK_WIDGET (self->desc_box)); + gtk_size_group_add_widget (group, GTK_WIDGET (self->title_box)); - g_set_object (&self->desc_size_group, group); + g_set_object (&self->title_size_group, group); } static void @@ -100,14 +110,6 @@ gtk_shortcuts_gesture_get_property (GObject *object, switch (prop_id) { - case PROP_SUBTITLE: - g_value_set_string (value, gtk_label_get_label (self->subtitle)); - break; - - case PROP_TITLE: - g_value_set_string (value, gtk_label_get_label (self->title)); - break; - case PROP_ICON: { GIcon *icon; @@ -117,6 +119,14 @@ gtk_shortcuts_gesture_get_property (GObject *object, } break; + case PROP_TITLE: + g_value_set_string (value, gtk_label_get_label (self->title)); + break; + + case PROP_SUBTITLE: + g_value_set_string (value, gtk_label_get_label (self->subtitle)); + break; + default: G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec); } @@ -132,24 +142,24 @@ gtk_shortcuts_gesture_set_property (GObject *object, switch (prop_id) { - case PROP_DESC_SIZE_GROUP: - gtk_shortcuts_gesture_set_desc_size_group (self, GTK_SIZE_GROUP (g_value_get_object (value))); - break; - case PROP_ICON: gtk_shortcuts_gesture_set_icon (self, g_value_get_object (value)); break; - case PROP_ICON_SIZE_GROUP: - gtk_shortcuts_gesture_set_icon_size_group (self, GTK_SIZE_GROUP (g_value_get_object (value))); + case PROP_TITLE: + gtk_label_set_label (self->title, g_value_get_string (value)); break; case PROP_SUBTITLE: gtk_label_set_label (self->subtitle, g_value_get_string (value)); break; - case PROP_TITLE: - gtk_label_set_label (self->title, g_value_get_string (value)); + case PROP_TITLE_SIZE_GROUP: + gtk_shortcuts_gesture_set_title_size_group (self, GTK_SIZE_GROUP (g_value_get_object (value))); + break; + + case PROP_ICON_SIZE_GROUP: + gtk_shortcuts_gesture_set_icon_size_group (self, GTK_SIZE_GROUP (g_value_get_object (value))); break; default: @@ -162,28 +172,43 @@ gtk_shortcuts_gesture_finalize (GObject *object) { GtkShortcutsGesture *self = GTK_SHORTCUTS_GESTURE (object); - g_clear_object (&self->desc_size_group); + g_clear_object (&self->title_size_group); g_clear_object (&self->icon_size_group); G_OBJECT_CLASS (gtk_shortcuts_gesture_parent_class)->finalize (object); } +static void +gtk_shortcuts_gesture_add (GtkContainer *container, + GtkWidget *widget) +{ + g_warning ("Can't add children to %s", G_OBJECT_TYPE_NAME (container)); +} + +static GType +gtk_shortcuts_gesture_child_type (GtkContainer *container) +{ + return G_TYPE_NONE; +} + static void gtk_shortcuts_gesture_class_init (GtkShortcutsGestureClass *klass) { + GtkContainerClass *container_class = GTK_CONTAINER_CLASS (klass); GObjectClass *object_class = G_OBJECT_CLASS (klass); object_class->finalize = gtk_shortcuts_gesture_finalize; object_class->get_property = gtk_shortcuts_gesture_get_property; object_class->set_property = gtk_shortcuts_gesture_set_property; - properties[PROP_DESC_SIZE_GROUP] = - g_param_spec_object ("desc-size-group", - P_("Description Size Group"), - P_("Description Size Group"), - GTK_TYPE_SIZE_GROUP, - (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); + container_class->add = gtk_shortcuts_gesture_add; + container_class->child_type = gtk_shortcuts_gesture_child_type; + /** + * GtkShortcutsGesture:icon: + * + * The icon used to represent the gesture. + */ properties[PROP_ICON] = g_param_spec_object ("icon", P_("Icon"), @@ -191,13 +216,29 @@ gtk_shortcuts_gesture_class_init (GtkShortcutsGestureClass *klass) G_TYPE_ICON, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); - properties[PROP_ICON_SIZE_GROUP] = - g_param_spec_object ("icon-size-group", - P_("Icon Size Group"), - P_("Icon Size Group"), - GTK_TYPE_SIZE_GROUP, - (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsGesture:title: + * + * The title for the gesture. + * + * This should be a short, one-line text that describes the action + * associated with the gesture. + */ + properties[PROP_TITLE] = + g_param_spec_string ("title", + P_("Title"), + P_("Title"), + NULL, + (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsGesture:subtitle: + * + * The subtitle for the gesture. + * + * This should be a short, one-line text that describes the gesture + * itself, e.g. "Two-finger swipe". + */ properties[PROP_SUBTITLE] = g_param_spec_string ("subtitle", P_("Subtitle"), @@ -205,12 +246,33 @@ gtk_shortcuts_gesture_class_init (GtkShortcutsGestureClass *klass) NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); - properties[PROP_TITLE] = - g_param_spec_string ("title", - P_("Title"), - P_("Title"), - NULL, - (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsGesture:title-size-group: + * + * The size group for the textual portion of this gesture. + * + * This is used internally by GTK+, and must not be modified by applications. + */ + properties[PROP_TITLE_SIZE_GROUP] = + g_param_spec_object ("title-size-group", + P_("Title Size Group"), + P_("Title Size Group"), + GTK_TYPE_SIZE_GROUP, + (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); + + /** + * GtkShortcutsShortcut:icon-size-group: + * + * The size group for the image portion of this gesture. + * + * This is used internally by GTK+, and must not be modified by applications. + */ + properties[PROP_ICON_SIZE_GROUP] = + g_param_spec_object ("icon-size-group", + P_("Icon Size Group"), + P_("Icon Size Group"), + GTK_TYPE_SIZE_GROUP, + (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); g_object_class_install_properties (object_class, LAST_PROP, properties); } @@ -224,20 +286,20 @@ gtk_shortcuts_gesture_init (GtkShortcutsGesture *self) self->image = g_object_new (GTK_TYPE_IMAGE, "visible", TRUE, NULL); - gtk_container_add (GTK_CONTAINER (self), GTK_WIDGET (self->image)); + GTK_CONTAINER_CLASS (gtk_shortcuts_gesture_parent_class)->add (GTK_CONTAINER (self), GTK_WIDGET (self->image)); - self->desc_box = g_object_new (GTK_TYPE_BOX, - "hexpand", TRUE, - "orientation", GTK_ORIENTATION_VERTICAL, - "visible", TRUE, - NULL); - gtk_container_add (GTK_CONTAINER (self), GTK_WIDGET (self->desc_box)); + self->title_box = g_object_new (GTK_TYPE_BOX, + "hexpand", TRUE, + "orientation", GTK_ORIENTATION_VERTICAL, + "visible", TRUE, + NULL); + GTK_CONTAINER_CLASS (gtk_shortcuts_gesture_parent_class)->add (GTK_CONTAINER (self), GTK_WIDGET (self->title_box)); self->title = g_object_new (GTK_TYPE_LABEL, "visible", TRUE, "xalign", 0.0f, NULL); - gtk_container_add (GTK_CONTAINER (self->desc_box), GTK_WIDGET (self->title)); + gtk_container_add (GTK_CONTAINER (self->title_box), GTK_WIDGET (self->title)); self->subtitle = g_object_new (GTK_TYPE_LABEL, "visible", TRUE, @@ -245,5 +307,5 @@ gtk_shortcuts_gesture_init (GtkShortcutsGesture *self) NULL); gtk_style_context_add_class (gtk_widget_get_style_context (GTK_WIDGET (self->subtitle)), "dim-label"); - gtk_container_add (GTK_CONTAINER (self->desc_box), GTK_WIDGET (self->subtitle)); + gtk_container_add (GTK_CONTAINER (self->title_box), GTK_WIDGET (self->subtitle)); } diff --git a/gtk/gtkshortcutsgestureprivate.h b/gtk/gtkshortcutsgesture.h similarity index 98% rename from gtk/gtkshortcutsgestureprivate.h rename to gtk/gtkshortcutsgesture.h index 63ced78b96..0b60b39840 100644 --- a/gtk/gtkshortcutsgestureprivate.h +++ b/gtk/gtkshortcutsgesture.h @@ -34,7 +34,7 @@ G_BEGIN_DECLS typedef struct _GtkShortcutsGesture GtkShortcutsGesture; typedef struct _GtkShortcutsGestureClass GtkShortcutsGestureClass; - +GDK_AVAILABLE_IN_3_20 GType gtk_shortcuts_gesture_get_type (void) G_GNUC_CONST; G_END_DECLS diff --git a/gtk/gtkshortcutsgroup.c b/gtk/gtkshortcutsgroup.c index a7cb08b319..1ac3fc5276 100644 --- a/gtk/gtkshortcutsgroup.c +++ b/gtk/gtkshortcutsgroup.c @@ -18,16 +18,29 @@ #include "config.h" -#include "gtkshortcutsgroupprivate.h" +#include "gtkshortcutsgroup.h" -#include "gtkshortcutsshortcutprivate.h" -#include "gtkshortcutsgestureprivate.h" +#include "gtkshortcutsshortcut.h" +#include "gtkshortcutsgesture.h" #include "gtklabel.h" #include "gtkorientable.h" #include "gtksizegroup.h" #include "gtkprivate.h" #include "gtkintl.h" +/** + * SECTION:gtkshortcutsgroup + * @Title: GtkShortcutsGroup + * @Short_description: Represents a group of shortcuts in a GtkShortcutsWindow + * + * A GtkShortcutsGroup represents a group of related keyboard shortcuts + * or gestures. The group has a title. It may optionally be associated with + * a view of the application, which can be used to show only relevant shortcuts + * depending on the application context. + * + * This widget is only meant to be used with #GtkShortcutsWindow. + */ + struct _GtkShortcutsGroup { GtkBox parent_instance; @@ -85,7 +98,7 @@ gtk_shortcuts_group_set_title_size_group (GtkShortcutsGroup *group, if (GTK_IS_SHORTCUTS_SHORTCUT (l->data)) g_object_set (l->data, "title-size-group", size_group, NULL); else if (GTK_IS_SHORTCUTS_GESTURE (l->data)) - g_object_set (l->data, "desc-size-group", size_group, NULL); + g_object_set (l->data, "title-size-group", size_group, NULL); } g_list_free (children); } @@ -111,6 +124,19 @@ gtk_shortcuts_group_get_height (GtkShortcutsGroup *group) return height; } +static void +gtk_shortcuts_group_add (GtkContainer *container, + GtkWidget *widget) +{ + if (GTK_IS_SHORTCUTS_SHORTCUT (widget) || + GTK_IS_SHORTCUTS_GESTURE (widget)) + GTK_CONTAINER_CLASS (gtk_shortcuts_group_parent_class)->add (container, widget); + else + g_warning ("Can't add children of type %s to %s", + G_OBJECT_TYPE_NAME (widget), + G_OBJECT_TYPE_NAME (container)); +} + static void gtk_shortcuts_group_get_property (GObject *object, guint prop_id, @@ -183,21 +209,46 @@ gtk_shortcuts_group_finalize (GObject *object) static void gtk_shortcuts_group_class_init (GtkShortcutsGroupClass *klass) { + GtkContainerClass *container_class = GTK_CONTAINER_CLASS (klass); GObjectClass *object_class = G_OBJECT_CLASS (klass); object_class->finalize = gtk_shortcuts_group_finalize; object_class->get_property = gtk_shortcuts_group_get_property; object_class->set_property = gtk_shortcuts_group_set_property; + container_class->add = gtk_shortcuts_group_add; + + /** + * GtkShortcutsGroup:title: + * + * The title for this group of shortcuts. + */ properties[PROP_TITLE] = g_param_spec_string ("title", P_("Title"), P_("Title"), NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + + /** + * GtkShortcutsGroup:view: + * + * An optional view that the shortcuts in this group are relevant for. + * The group will be hidden if the #GtkShortcutsWindow:view-name property + * does not match the view of this group. + * + * Set this to %NULL to make the group always visible. + */ properties[PROP_VIEW] = g_param_spec_string ("view", P_("View"), P_("View"), NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsGroup:accel-size-group: + * + * The size group for the accelerator portion of shortcuts in this group. + * + * This is used internally by GTK+, and must not be modified by applications. + */ properties[PROP_ACCEL_SIZE_GROUP] = g_param_spec_object ("accel-size-group", P_("Accelerator Size Group"), @@ -205,6 +256,13 @@ gtk_shortcuts_group_class_init (GtkShortcutsGroupClass *klass) GTK_TYPE_SIZE_GROUP, (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsGroup:title-size-group: + * + * The size group for the textual portion of shortcuts in this group. + * + * This is used internally by GTK+, and must not be modified by applications. + */ properties[PROP_TITLE_SIZE_GROUP] = g_param_spec_object ("title-size-group", P_("Title Size Group"), @@ -212,6 +270,13 @@ gtk_shortcuts_group_class_init (GtkShortcutsGroupClass *klass) GTK_TYPE_SIZE_GROUP, (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsGroup:height: + * + * A rough measure for the number of lines in this group. + * + * This is used internally by GTK+, and is not useful for applications. + */ properties[PROP_HEIGHT] = g_param_spec_uint ("height", P_("Height"), P_("Height"), 0, G_MAXUINT, 0, @@ -235,6 +300,7 @@ gtk_shortcuts_group_init (GtkShortcutsGroup *self) "visible", TRUE, "xalign", 0.0f, NULL); - gtk_container_add (GTK_CONTAINER (self), GTK_WIDGET (self->title)); pango_attr_list_unref (attrs); + + GTK_CONTAINER_CLASS (gtk_shortcuts_group_parent_class)->add (GTK_CONTAINER (self), GTK_WIDGET (self->title)); } diff --git a/gtk/gtkshortcutsgroupprivate.h b/gtk/gtkshortcutsgroup.h similarity index 98% rename from gtk/gtkshortcutsgroupprivate.h rename to gtk/gtkshortcutsgroup.h index 4b27ec40a6..790d60a855 100644 --- a/gtk/gtkshortcutsgroupprivate.h +++ b/gtk/gtkshortcutsgroup.h @@ -34,6 +34,7 @@ G_BEGIN_DECLS typedef struct _GtkShortcutsGroup GtkShortcutsGroup; typedef struct _GtkShortcutsGroupClass GtkShortcutsGroupClass; +GDK_AVAILABLE_IN_3_20 GType gtk_shortcuts_group_get_type (void) G_GNUC_CONST; G_END_DECLS diff --git a/gtk/gtkshortcutssection.c b/gtk/gtkshortcutssection.c index fa8662b508..5475f264d2 100644 --- a/gtk/gtkshortcutssection.c +++ b/gtk/gtkshortcutssection.c @@ -18,9 +18,9 @@ #include "config.h" -#include "gtkshortcutssectionprivate.h" +#include "gtkshortcutssection.h" -#include "gtkshortcutsgroupprivate.h" +#include "gtkshortcutsgroup.h" #include "gtktogglebutton.h" #include "gtkstack.h" #include "gtkstackswitcher.h" @@ -31,6 +31,23 @@ #include "gtkprivate.h" #include "gtkintl.h" +/** + * SECTION:gtkshortcutssection + * @Title: GtkShortcutsSection + * @Short_description: Represents an application mode in a GtkShortcutsWindow + * + * A GtkShortcutsSection collects all the keyboard shortcuts and gestures + * for a major application mode. If your application needs multiple sections, + * you should give each section a unique #GtkShortcutsSection:section-name and + * a #GtkShortcutsSection:title that can be shown in the section selector of + * the GtkShortcutsWindow. + * + * The #GtkShortcutsSection:max-height property can be used to influence how + * the groups in the section are distributed over pages and columns. + * + * This widget is only meant to be used with #GtkShortcutsWindow. + */ + struct _GtkShortcutsSection { GtkBox parent_instance; @@ -97,7 +114,9 @@ gtk_shortcuts_section_add (GtkContainer *container, if (GTK_IS_SHORTCUTS_GROUP (child)) gtk_shortcuts_section_add_group (self, GTK_SHORTCUTS_GROUP (child)); else - GTK_CONTAINER_CLASS (gtk_shortcuts_section_parent_class)->add (container, child); + g_warning ("Can't add children of type %s to %s", + G_OBJECT_TYPE_NAME (child), + G_OBJECT_TYPE_NAME (container)); } static void @@ -175,6 +194,12 @@ gtk_shortcuts_section_set_property (GObject *object, } } +static GType +gtk_shortcuts_section_child_type (GtkContainer *container) +{ + return GTK_TYPE_SHORTCUTS_GROUP; +} + static void gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass) { @@ -189,22 +214,55 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass) widget_class->map = gtk_shortcuts_section_map; container_class->add = gtk_shortcuts_section_add; + container_class->child_type = gtk_shortcuts_section_child_type; + /** + * GtkShortcutsSection:section-name: + * + * A unique name to identify this section among the sections + * added to the GtkShortcutsWindow. Setting the #GtkShortcutsWindow:section-name + * property to this string will make this section shown in the + * GtkShortcutsWindow. + */ properties[PROP_SECTION_NAME] = g_param_spec_string ("section-name", P_("Section Name"), P_("Section Name"), NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsSection:view-name: + * + * A view name to filter the groups in this section by. + * See #GtkShortcutsGroup:view. + * + * Applications are expected to use the #GtkShortcutsWindow:view-name + * property for this purpose. + */ properties[PROP_VIEW_NAME] = g_param_spec_string ("view-name", P_("View Name"), P_("View Name"), NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsSection:title: + * + * The string to show in the section selector of the GtkShortcutsWindow + * for this section. If there is only one section, you don't need to + * set a title, since the section selector will not be shown in this case. + */ properties[PROP_TITLE] = g_param_spec_string ("title", P_("Title"), P_("Title"), NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsSection:max-height: + * + * The maximum number of lines to allow per column. This property can + * be used to influence how the groups in this section are distributed + * across pages and columns. The default value of 15 should work in + * for most cases. + */ properties[PROP_MAX_HEIGHT] = g_param_spec_uint ("max-height", P_("Maximum Height"), P_("Maximum Height"), 0, G_MAXUINT, 15, @@ -231,7 +289,7 @@ gtk_shortcuts_section_init (GtkShortcutsSection *self) "vexpand", TRUE, "visible", TRUE, NULL); - gtk_container_add (GTK_CONTAINER (self), GTK_WIDGET (self->stack)); + GTK_CONTAINER_CLASS (gtk_shortcuts_section_parent_class)->add (GTK_CONTAINER (self), GTK_WIDGET (self->stack)); self->switcher = g_object_new (GTK_TYPE_STACK_SWITCHER, "halign", GTK_ALIGN_CENTER, @@ -248,7 +306,7 @@ gtk_shortcuts_section_init (GtkShortcutsSection *self) G_CALLBACK (show_all_changed), self); box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 20); - gtk_container_add (GTK_CONTAINER (self), box); + GTK_CONTAINER_CLASS (gtk_shortcuts_section_parent_class)->add (GTK_CONTAINER (self), box); gtk_box_set_center_widget (GTK_BOX (box), GTK_WIDGET (self->switcher)); gtk_box_pack_end (GTK_BOX (box), self->show_all, TRUE, TRUE, 0); diff --git a/gtk/gtkshortcutssectionprivate.h b/gtk/gtkshortcutssection.h similarity index 96% rename from gtk/gtkshortcutssectionprivate.h rename to gtk/gtkshortcutssection.h index f5d48976ee..1f3d33939e 100644 --- a/gtk/gtkshortcutssectionprivate.h +++ b/gtk/gtkshortcutssection.h @@ -1,4 +1,4 @@ -/* gtkshortcutssectionprivate.h +/* gtkshortcutssection.h * * Copyright (C) 2015 Christian Hergert * @@ -20,7 +20,7 @@ #define __GTK_SHORTCUTS_SECTION_H__ #include -#include +#include G_BEGIN_DECLS @@ -35,7 +35,7 @@ G_BEGIN_DECLS typedef struct _GtkShortcutsSection GtkShortcutsSection; typedef struct _GtkShortcutsSectionClass GtkShortcutsSectionClass; - +GDK_AVAILABLE_IN_3_20 GType gtk_shortcuts_section_get_type (void) G_GNUC_CONST; const gchar *gtk_shortcuts_section_get_section_name (GtkShortcutsSection *self); diff --git a/gtk/gtkshortcutsshortcut.c b/gtk/gtkshortcutsshortcut.c index 2a3d0310a8..c14eb0a455 100644 --- a/gtk/gtkshortcutsshortcut.c +++ b/gtk/gtkshortcutsshortcut.c @@ -18,12 +18,21 @@ #include "config.h" -#include "gtkshortcutsshortcutprivate.h" +#include "gtkshortcutsshortcut.h" #include "gtkshortcutlabelprivate.h" #include "gtkprivate.h" #include "gtkintl.h" +/** + * SECTION:gtkshortcutsshortcut + * @Title: GtkShortcutsShortcut + * @Short_description: Represents a keyboard shortcut in a GtkShortcutsWindow + * + * A GtkShortcutsShortcut represents a single keyboard shortcut with + * a short text. This widget is only meant to be used with + * #GtkShortcutsWindow. + */ struct _GtkShortcutsShortcut { @@ -46,8 +55,8 @@ G_DEFINE_TYPE (GtkShortcutsShortcut, gtk_shortcuts_shortcut, GTK_TYPE_BOX) enum { PROP_0, PROP_ACCELERATOR, - PROP_ACCEL_SIZE_GROUP, PROP_TITLE, + PROP_ACCEL_SIZE_GROUP, PROP_TITLE_SIZE_GROUP, LAST_PROP }; @@ -144,15 +153,45 @@ gtk_shortcuts_shortcut_finalize (GObject *object) G_OBJECT_CLASS (gtk_shortcuts_shortcut_parent_class)->finalize (object); } +static void +gtk_shortcuts_shortcut_add (GtkContainer *container, + GtkWidget *widget) +{ + g_warning ("Can't add children to %s", G_OBJECT_TYPE_NAME (container)); +} + +static GType +gtk_shortcuts_shortcut_child_type (GtkContainer *container) +{ + return G_TYPE_NONE; +} + static void gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass) { + GtkContainerClass *container_class = GTK_CONTAINER_CLASS (klass); GObjectClass *object_class = G_OBJECT_CLASS (klass); object_class->finalize = gtk_shortcuts_shortcut_finalize; object_class->get_property = gtk_shortcuts_shortcut_get_property; object_class->set_property = gtk_shortcuts_shortcut_set_property; + container_class->add = gtk_shortcuts_shortcut_add; + container_class->child_type = gtk_shortcuts_shortcut_child_type; + + /** + * GtkShortcutsShortcut:accelerator: + * + * The accelerator(s) represented by this object, in the syntax + * understood by gtk_accelerator_parse(). Multiple accelerators + * can be specified by separating them with a space, but keep in + * mind that the available width is limited. + * + * Here is an example: ? F1 + * + * Note that < and > need to escaped as < and > when used + * in .ui files. + */ properties[PROP_ACCELERATOR] = g_param_spec_string ("accelerator", P_("Accelerator"), @@ -160,13 +199,13 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass) NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); - properties[PROP_ACCEL_SIZE_GROUP] = - g_param_spec_object ("accel-size-group", - P_("Accelerator Size Group"), - P_("Accelerator Size Group"), - GTK_TYPE_SIZE_GROUP, - (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); - + /** + * GtkShortcutsShortcut:title: + * + * The textual description for the accelerators represented by + * this object. This should be a short string that can fit in + * a single line. + */ properties[PROP_TITLE] = g_param_spec_string ("title", P_("Title"), @@ -174,6 +213,27 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass) NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + /** + * GtkShortcutsShortcut:accel-size-group: + * + * The size group for the accelerator portion of this shortcut. + * + * This is used internally by GTK+, and must not be modified by applications. + */ + properties[PROP_ACCEL_SIZE_GROUP] = + g_param_spec_object ("accel-size-group", + P_("Accelerator Size Group"), + P_("Accelerator Size Group"), + GTK_TYPE_SIZE_GROUP, + (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)); + + /** + * GtkShortcutsShortcut:title-size-group: + * + * The size group for the textual portion of this shortcut. + * + * This is used internally by GTK+, and must not be modified by applications. + */ properties[PROP_TITLE_SIZE_GROUP] = g_param_spec_object ("title-size-group", P_("Title Size Group"), @@ -193,12 +253,12 @@ gtk_shortcuts_shortcut_init (GtkShortcutsShortcut *self) self->accelerator = g_object_new (GTK_TYPE_SHORTCUT_LABEL, "visible", TRUE, NULL); - gtk_container_add (GTK_CONTAINER (self), GTK_WIDGET (self->accelerator)); + GTK_CONTAINER_CLASS (gtk_shortcuts_shortcut_parent_class)->add (GTK_CONTAINER (self), GTK_WIDGET (self->accelerator)); self->title = g_object_new (GTK_TYPE_LABEL, "hexpand", TRUE, "visible", TRUE, "xalign", 0.0f, NULL); - gtk_container_add (GTK_CONTAINER (self), GTK_WIDGET (self->title)); + GTK_CONTAINER_CLASS (gtk_shortcuts_shortcut_parent_class)->add (GTK_CONTAINER (self), GTK_WIDGET (self->title)); } diff --git a/gtk/gtkshortcutsshortcutprivate.h b/gtk/gtkshortcutsshortcut.h similarity index 98% rename from gtk/gtkshortcutsshortcutprivate.h rename to gtk/gtkshortcutsshortcut.h index 9c30445c41..57d76ad60e 100644 --- a/gtk/gtkshortcutsshortcutprivate.h +++ b/gtk/gtkshortcutsshortcut.h @@ -35,6 +35,7 @@ typedef struct _GtkShortcutsShortcut GtkShortcutsShortcut; typedef struct _GtkShortcutsShortcutClass GtkShortcutsShortcutClass; +GDK_AVAILABLE_IN_3_20 GType gtk_shortcuts_shortcut_get_type (void) G_GNUC_CONST; G_END_DECLS diff --git a/gtk/gtkshortcutswindow.c b/gtk/gtkshortcutswindow.c index f8305d1505..7a1bc486df 100644 --- a/gtk/gtkshortcutswindow.c +++ b/gtk/gtkshortcutswindow.c @@ -20,24 +20,58 @@ #include "gtkshortcutswindow.h" #include "gtkscrolledwindow.h" -#include "gtkshortcutsgestureprivate.h" -#include "gtkshortcutsgroupprivate.h" -#include "gtkshortcutsshortcutprivate.h" -#include "gtkshortcutssectionprivate.h" +#include "gtkshortcutssection.h" +#include "gtkshortcutsgroup.h" +#include "gtkshortcutsgesture.h" +#include "gtkshortcutsshortcut.h" #include "gtkprivate.h" #include "gtkintl.h" /** * SECTION:gtkshortcutswindow - * @title: GtkShortcutsWindow - * @short_description: Toplevel which shows help for shortcuts + * @Title: GtkShortcutsWindow + * @Short_description: Toplevel which shows help for shortcuts * - * A GtkShortcutsWindow shows brief information about keyboard shortcuts - * and gestures, sorted in pages, columns and groups. + * A GtkShortcutsWindow shows brief information about the keyboard shortcuts + * and gestures of an application. The shortcuts can be grouped, and you can + * have multiple sections in this window, corresponding to the major modes of + * your application. * - * The recommended way to construct a GtkShortcutsWindow is with GtkBuilder: + * Additionally, the shortcuts can be filtered by the current view, to avoid + * showing information that is not relevant in the current application context. * - * [A simple example](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts.ui) + * The recommended way to construct a GtkShortcutsWindow is with GtkBuilder, + * by populating a #GtkShortcutsWindow with one or more #GtkShortcutsSection + * objects, which contain #GtkShortcutsGroups that in turn contain objects of + * class #GtkShortcutsShortcut or #GtkShortcutsGesture. + * + * # A simple example: + * + * ![](gedit-shortcuts.png) + * + * This example has as single section. As you can see, the shortcut groups + * are arranged in columns, and spread across several pages if there are too + * many to find on a single page. + * + * The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-gedit.ui). + * + * # An example with multiple views: + * + * ![](clocks-shortcuts.png) + * + * This example shows a #GtkShortcutsWindow that has been configured to show only + * the shortcuts relevant to the "stopwatch" view. + * + * The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-clocks.ui). + * + * # An example with multiple sections: + * + * ![](builder-shortcuts.png) + * + * This example shows a #GtkShortcutsWindow with two sections, "Editor Shortcuts" + * and "Terminal Shortcuts". + * + * The .ui file for this example can be found [here](https://git.gnome.org/browse/gtk+/tree/demos/gtk-demo/shortcuts-clocks.ui). */ typedef struct @@ -208,7 +242,7 @@ gtk_shortcuts_window_add_search_item (GtkWidget *child, gpointer data) "subtitle", subtitle, "icon", icon, "icon-size-group", priv->search_image_group, - "desc-size-group", priv->search_text_group, + "title-size-group", priv->search_text_group, NULL); str = g_strdup_printf ("%s %s", title, subtitle); @@ -269,14 +303,16 @@ gtk_shortcuts_window_add_section (GtkShortcutsWindow *self, static void gtk_shortcuts_window_add (GtkContainer *container, - GtkWidget *widget) + GtkWidget *widget) { GtkShortcutsWindow *self = (GtkShortcutsWindow *)container; if (GTK_IS_SHORTCUTS_SECTION (widget)) gtk_shortcuts_window_add_section (self, GTK_SHORTCUTS_SECTION (widget)); else - GTK_CONTAINER_CLASS (gtk_shortcuts_window_parent_class)->add (container, widget); + g_warning ("Can't add children of type %s to %s", + G_OBJECT_TYPE_NAME (widget), + G_OBJECT_TYPE_NAME (container)); } static void @@ -492,6 +528,12 @@ gtk_shortcuts_window_set_property (GObject *object, } } +static GType +gtk_shortcuts_window_child_type (GtkContainer *container) +{ + return GTK_TYPE_SHORTCUTS_SECTION; +} + static void gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass) { @@ -505,13 +547,33 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass) object_class->set_property = gtk_shortcuts_window_set_property; container_class->add = gtk_shortcuts_window_add; + container_class->child_type = gtk_shortcuts_window_child_type; klass->close = gtk_shortcuts_window_real_close; + /** + * GtkShortcutsWindow:section-name: + * + * The name of the section to show. + * + * This should be the section-name of one of the #GtkShortcutsSection + * objects that are in this shortcuts window. + */ properties[PROP_SECTION_NAME] = g_param_spec_string ("section-name", P_("Section Name"), P_("Section Name"), NULL, (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); + + /** + * GtkShortcutsWindow:view-name: + * + * The view name by which to filter the contents. + * + * This should correspond to the #GtkShortcutsGroup:view property of some of + * the #GtkShortcutsGroup objects that are inside this shortcuts window. + * + * Set this to %NULL to show all groups. + */ properties[PROP_VIEW_NAME] = g_param_spec_string ("view-name", P_("View Name"), P_("View Name"), NULL, @@ -519,6 +581,16 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass) g_object_class_install_properties (object_class, LAST_PROP, properties); + /** + * GtkShortcutsWindow::close: + * + * The ::close signal is a + * [keybinding signal][GtkBindingSignal] + * which gets emitted when the user uses a keybinding to close + * the window. + * + * The default binding for this signal is the Escape key. + */ signals[CLOSE] = g_signal_new (I_("close"), G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION, @@ -589,7 +661,7 @@ gtk_shortcuts_window_init (GtkShortcutsWindow *self) "orientation", GTK_ORIENTATION_VERTICAL, "visible", TRUE, NULL); - gtk_container_add (GTK_CONTAINER (self), GTK_WIDGET (main_box)); + GTK_CONTAINER_CLASS (gtk_shortcuts_window_parent_class)->add (GTK_CONTAINER (self), GTK_WIDGET (main_box)); priv->search_bar = g_object_new (GTK_TYPE_SEARCH_BAR, "visible", TRUE, diff --git a/gtk/gtkshortcutswindow.h b/gtk/gtkshortcutswindow.h index 729e3188f7..00a1022d8f 100644 --- a/gtk/gtkshortcutswindow.h +++ b/gtk/gtkshortcutswindow.h @@ -47,6 +47,7 @@ struct _GtkShortcutsWindowClass void (*close) (GtkShortcutsWindow *self); }; +GDK_AVAILABLE_IN_3_20 GType gtk_shortcuts_window_get_type (void) G_GNUC_CONST;