[PATCH 3/4] Create/clarify some documentation in the custom widgets.
Martin Sivak
msivak at redhat.com
Tue Jan 29 14:42:20 UTC 2013
Ack.
----- Original Message -----
> ---
> widgets/src/BaseWindow.c | 39
> ++++++++++++++++++++++++++++++---------
> widgets/src/MountpointSelector.c | 2 +-
> widgets/src/SpokeSelector.c | 17 ++++++++++++++---
> widgets/src/SpokeWindow.c | 11 +++++++----
> 4 files changed, 52 insertions(+), 17 deletions(-)
>
> diff --git a/widgets/src/BaseWindow.c b/widgets/src/BaseWindow.c
> index f417260..7493ca4 100644
> --- a/widgets/src/BaseWindow.c
> +++ b/widgets/src/BaseWindow.c
> @@ -133,6 +133,8 @@ static void
> anaconda_base_window_class_init(AnacondaBaseWindowClass *klass) {
> *
> * The name of the currently displayed window, displayed in the
> upper
> * left corner of all windows with a title throughout
> installation.
> + * StandaloneWindows should not have a title, so no name will be
> displayed
> + * for those.
> *
> * Since: 1.0
> */
> @@ -151,7 +153,8 @@ static void
> anaconda_base_window_class_init(AnacondaBaseWindowClass *klass) {
> * @window: the window that received the signal
> *
> * Emitted when a visible info bar at the bottom of the window
> has been clicked
> - * (pressed and released).
> + * (pressed and released). This allows, for instance, popping
> up a dialog with
> + * more detailed information.
> *
> * Since: 1.0
> */
> @@ -189,6 +192,9 @@ static void
> anaconda_base_window_init(AnacondaBaseWindow *win) {
> win->priv->is_beta = FALSE;
> win->priv->info_shown = FALSE;
>
> + /* These store the original English strings so that when we
> retranslate
> + * later, we have the source strings available to feed into _().
> + */
> win->priv->orig_name = NULL;
> win->priv->orig_distro = NULL;
> win->priv->orig_beta = NULL;
> @@ -259,7 +265,7 @@ static void
> anaconda_base_window_init(AnacondaBaseWindow *win) {
>
> win->priv->orig_distro = g_strdup(DEFAULT_DISTRIBUTION);
>
> - /* Create the betanag label. */
> + /* Create the beta label. */
> win->priv->beta_label = gtk_label_new(NULL);
> markup = g_markup_printf_escaped("<span foreground='red'
> weight='bold' size='large'>%s</span>", _(DEFAULT_BETA));
> gtk_label_set_markup(GTK_LABEL(win->priv->beta_label), markup);
> @@ -323,7 +329,7 @@ static void
> anaconda_base_window_set_property(GObject *object, guint prop_id, co
> * anaconda_base_window_get_beta:
> * @win: a #AnacondaBaseWindow
> *
> - * Returns whether or not this window is set to display the betanag
> warning.
> + * Returns whether or not this window is set to display the beta
> label.
> *
> * Returns: Whether @win is set to display the betanag warning
> *
> @@ -338,8 +344,8 @@ gboolean
> anaconda_base_window_get_beta(AnacondaBaseWindow *win) {
> * @win: a #AnacondaBaseWindow
> * @is_beta: %TRUE to display the betanag warning
> *
> - * Sets up the window to display the betanag warning in red along
> the top of
> - * the screen.
> + * Sets up the window to display the beta label in red along the top
> of the
> + * screen.
> *
> * Since: 1.0
> */
> @@ -356,7 +362,8 @@ void
> anaconda_base_window_set_beta(AnacondaBaseWindow *win, gboolean
> is_beta) {
> * anaconda_base_window_get_action_area:
> * @win: a #AnacondaBaseWindow
> *
> - * Returns the action area of @win.
> + * Returns the action area of @win. This is the area of the screen
> where most
> + * of the widgets the user interacts with will live.
> *
> * Returns: (transfer none): The action area
> *
> @@ -370,7 +377,9 @@ GtkWidget
> *anaconda_base_window_get_action_area(AnacondaBaseWindow *win) {
> * anaconda_base_window_get_nav_area:
> * @win: a #AnacondaBaseWindow
> *
> - * Returns the navigation area of @win.
> + * Returns the navigation area of @win. This is the area at the top
> of the
> + * screen displaying the window's title (if it has one),
> distribution, and
> + * so forth.
> *
> * Returns: (transfer none): The navigation area
> *
> @@ -385,6 +394,8 @@ GtkWidget
> *anaconda_base_window_get_nav_area(AnacondaBaseWindow *win) {
> * @win: a #AnacondaBaseWindow
> *
> * Returns the event box that houses background window of the
> navigation area of @win.
> + * Currently, this is only used by #AnacondaSpokeWindow to have a
> place to store the
> + * gradient image. This function should probably not be used
> elsewhere.
> *
> * Returns: (transfer none): The event box
> *
> @@ -398,7 +409,10 @@ GtkWidget
> *anaconda_base_window_get_nav_area_background_window(AnacondaBaseWindo
> * anaconda_base_window_get_main_box:
> * @win: a #AnacondaBaseWindow
> *
> - * Returns the main content area of @win.
> + * Returns the main content area of @win. This widget holds both
> the action_area
> + * and the nav_area. Currently, this is only used by
> #AnacondaStandaloneWindow
> + * as a place to store the extra Continue button. This function
> should probably
> + * not be used elsewhere.
> *
> * Returns: (transfer none): The main content area
> *
> @@ -412,7 +426,9 @@ GtkWidget
> *anaconda_base_window_get_main_box(AnacondaBaseWindow *win) {
> * anaconda_base_window_get_alignment:
> * @win: a #AnacondaBaseWindow
> *
> - * Returns the internal alignment widget of @win.
> + * Returns the internal alignment widget of @win. Currently, this
> is only used
> + * by #AnacondaHubWindow to set different alignment values than the
> spokes have.
> + * This function should probably not be used elsewhere.
> *
> * Returns: (transfer none): The alignment widget
> *
> @@ -553,6 +569,7 @@ void
> anaconda_base_window_retranslate(AnacondaBaseWindow *win, const char
> *lang)
> setenv("LANGUAGE", lang, 1);
> setlocale(LC_ALL, "");
>
> + /* This bit is internal gettext magic. */
> {
> extern int _nl_msg_cat_cntr;
> ++_nl_msg_cat_cntr;
> @@ -594,6 +611,10 @@ static GObject *
> anaconda_base_window_buildable_get_internal_child (GtkBuildable
> *buildable,
> GtkBuilder
> *builder,
> const gchar
> *childname) {
> + /* Note that if you add more internal children and want them to
> be accessible,
> + * all their parents must also be made accessible. This goes
> all the way up
> + * to the top level.
> + */
> if (!strcmp(childname, "main_box"))
> return
> G_OBJECT(anaconda_base_window_get_main_box(ANACONDA_BASE_WINDOW(buildable)));
> else if (!strcmp(childname, "nav_area"))
> diff --git a/widgets/src/MountpointSelector.c
> b/widgets/src/MountpointSelector.c
> index 160c43f..3b9a09f 100644
> --- a/widgets/src/MountpointSelector.c
> +++ b/widgets/src/MountpointSelector.c
> @@ -31,7 +31,7 @@
> * @short_description: A graphical way to select a mount point.
> *
> * A #AnacondaMountpointSelector is a widget that appears on the
> custom partitioning
> - * Mountpoint and allows the user to select a single mount point to
> do additional
> + * spoke and allows the user to select a single mount point to do
> additional
> * configuration.
> *
> * As a #AnacondaMountpointSelector is a subclass of a #GtkEventBox,
> any signals
> diff --git a/widgets/src/SpokeSelector.c
> b/widgets/src/SpokeSelector.c
> index e6c23cc..c459667 100644
> --- a/widgets/src/SpokeSelector.c
> +++ b/widgets/src/SpokeSelector.c
> @@ -35,7 +35,7 @@
> * configuration and allows for a place to click to do further
> configuration.
> *
> * Some Spokes can have their initial configuration guessed, while
> others
> - * (specifically storage) requires the user to do something. For
> those that
> + * (specifically storage) require the user to do something. For
> those that
> * the user has not entered, the selector may be set as incomplete.
> See
> * #anaconda_spoke_selector_get_incomplete and
> #anaconda_spoke_selector_set_incomplete.
> *
> @@ -103,7 +103,8 @@ static void
> anaconda_spoke_selector_class_init(AnacondaSpokeSelectorClass *klass
> * The :status string is text displayed underneath the spoke's
> :title and
> * also beside the :icon. This text very briefly describes what
> has been
> * selected on the spoke associated with this selector. For
> instance, it
> - * might be set up to "English" for a language-related spoke.
> + * might be set up to "English" for a language-related spoke.
> Special
> + * formatting will be applied to error status text for
> incomplete spokes.
> *
> * Since: 1.0
> */
> @@ -119,7 +120,9 @@ static void
> anaconda_spoke_selector_class_init(AnacondaSpokeSelectorClass *klass
> * AnacondaSpokeSelector:title:
> *
> * The :title of this selector, which will be displayed large
> and bold
> - * beside the :icon.
> + * beside the :icon. The title string should contain a keyboard
> mnemonic
> + * (a letter preceeded by an underscore), in which case this
> will be the
> + * keystroke that can be used to focus this selector.
> *
> * Since: 1.0
> */
> @@ -155,6 +158,7 @@ static void
> format_status_label(AnacondaSpokeSelector *spoke, const char *markup
> pango_attr_list_insert(attrs,
> pango_attr_style_new(PANGO_STYLE_ITALIC));
> pango_attr_list_insert(attrs,
> pango_attr_scale_new(PANGO_SCALE_LARGE));
>
> + /* Display error text in a dark red color to draw the user's
> attention. */
> if (anaconda_spoke_selector_get_incomplete(spoke) &&
> gtk_widget_get_sensitive(GTK_WIDGET(spoke))) {
> pango_attr_list_insert(attrs,
> pango_attr_foreground_new(0xcccc, 0x1a1a, 0x1a1a));
> @@ -208,6 +212,13 @@ static void
> anaconda_spoke_selector_init(AnacondaSpokeSelector *spoke) {
> gtk_widget_set_valign(spoke->priv->icon, GTK_ALIGN_CENTER);
> gtk_misc_set_padding(GTK_MISC(spoke->priv->icon), 12, 0);
>
> + /* This little warning icon will be displayed near the title
> when the
> + * spoke is incomplete. We just make it here in advance so we
> don't have
> + * to make/destroy it on demand.
> + */
> + /* FIXME: This should really be displayed over the corner of the
> spoke's
> + * icon because it looks like it's floating off in space right
> now.
> + */
> spoke->priv->incomplete_icon =
> gtk_image_new_from_icon_name("dialog-warning-symbolic",
> GTK_ICON_SIZE_MENU);
> gtk_widget_set_no_show_all(GTK_WIDGET(spoke->priv->incomplete_icon),
> TRUE);
> gtk_widget_set_visible(GTK_WIDGET(spoke->priv->incomplete_icon),
> FALSE);
> diff --git a/widgets/src/SpokeWindow.c b/widgets/src/SpokeWindow.c
> index 2874e58..2db0efe 100644
> --- a/widgets/src/SpokeWindow.c
> +++ b/widgets/src/SpokeWindow.c
> @@ -77,8 +77,8 @@ static void
> anaconda_spoke_window_class_init(AnacondaSpokeWindowClass *klass) {
> * AnacondaSpokeWindow:button-label:
> *
> * The :button-label string is the text used to label the button
> displayed
> - * in the upper lefthand of the window. By default, this is a
> back button
> - * but could be anything else appropriate.
> + * in the upper lefthand of the window. By default, this button
> says Done,
> + * but it could be changed to anything appropriate.
> *
> * Since: 1.0
> */
> @@ -96,7 +96,10 @@ static void
> anaconda_spoke_window_class_init(AnacondaSpokeWindowClass *klass) {
> *
> * Emitted when the button in the upper left corner has been
> activated
> * (pressed and released). This is commonly the button that
> takes the user
> - * back to the hub, but could do other things.
> + * back to the hub, but could do other things. Note that we do
> not want
> + * to trap people in spokes, so there should always be a way
> back to the
> + * hub via this signal, even if it involves canceling some
> operation or
> + * resetting things.
> *
> * Since: 1.0
> */
> @@ -136,7 +139,7 @@ static void
> anaconda_spoke_window_init(AnacondaSpokeWindow *win) {
> /* Set some default properties. */
> gtk_window_set_modal(GTK_WINDOW(win), TRUE);
>
> - /* Create the buttons. */
> + /* Create the button. */
> win->priv->button =
> gtk_button_new_with_mnemonic(DEFAULT_BUTTON_LABEL);
> gtk_widget_set_halign(win->priv->button, GTK_ALIGN_START);
>
> --
> 1.7.11.2
>
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
>
More information about the anaconda-patches
mailing list