[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