gnome-shell/src/gtkmenutracker.c

/*
 * Copyright © 2013 Canonical Limited
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the licence, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 * Author: Ryan Lortie <desrt@desrt.ca>
 */

#include "config.h"

#include "gtkmenutracker.h"

/**
 * SECTION:gtkmenutracker
 * @Title: GtkMenuTracker
 * @Short_description: A helper class for interpreting #GMenuModel
 *
 * #GtkMenuTracker is a simple object to ease implementations of #GMenuModel.
 * Given a #GtkActionObservable (usually a #GActionMuxer) along with a
 * #GMenuModel, it will tell you which menu items to create and where to place
 * them. If a menu item is removed, it will tell you the position of the menu
 * item to remove.
 *
 * Using #GtkMenuTracker is fairly simple. The only guarantee you must make
 * to #GtkMenuTracker is that you must obey all insert signals and track the
 * position of items that #GtkMenuTracker gives you. That is, #GtkMenuTracker
 * expects positions of all the latter items to change when it calls your
 * insertion callback with an early position, as it may ask you to remove
 * an item with a readjusted position later.
 *
 * #GtkMenuTracker will give you a #GtkMenuTrackerItem in your callback. You
 * must hold onto this object until a remove signal is emitted. This item
 * represents a single menu item, which can be one of three classes: normal item,
 * separator, or submenu.
 *
 * Certain properties on the #GtkMenuTrackerItem are mutable, and you must
 * listen for changes in the item. For more details, see the documentation
 * for #GtkMenuTrackerItem along with https://live.gnome.org/GApplication/GMenuModel.
 *
 * The idea of @with_separators is for special cases where menu models may
 * be tracked in places where separators are not available, like in toplevel
 * "File", "Edit" menu bars. Ignoring separator items is wrong, as #GtkMenuTracker
 * expects the position to change, so we must tell #GtkMenuTracker to ignore
 * separators itself.
 */

typedef struct _GtkMenuTrackerSection GtkMenuTrackerSection;

struct _GtkMenuTracker
{
  GtkActionObservable      *observable;
  GtkMenuTrackerInsertFunc  insert_func;
  GtkMenuTrackerRemoveFunc  remove_func;
  gpointer                  user_data;

  GtkMenuTrackerSection    *toplevel;
};

struct _GtkMenuTrackerSection
{
  GMenuModel *model;
  GSList     *items;
  gchar      *action_namespace;

  guint       with_separators : 1;
  guint       has_separator   : 1;

  gulong      handler;
};

static GtkMenuTrackerSection *  gtk_menu_tracker_section_new    (GtkMenuTracker        *tracker,
                                                                 GMenuModel            *model,
                                                                 gboolean               with_separators,
                                                                 gint                   offset,
                                                                 const gchar           *action_namespace);
static void                    gtk_menu_tracker_section_free    (GtkMenuTrackerSection *section);

static GtkMenuTrackerSection *
gtk_menu_tracker_section_find_model (GtkMenuTrackerSection *section,
                                     GMenuModel            *model,
                                     gint                  *offset)
{
  GSList *item;

  if (section->has_separator)
    (*offset)++;

  if (section->model == model)
    return section;

  for (item = section->items; item; item = item->next)
    {
      GtkMenuTrackerSection *subsection = item->data;

      if (subsection)
        {
          GtkMenuTrackerSection *found_section;

          found_section = gtk_menu_tracker_section_find_model (subsection, model, offset);

          if (found_section)
            return found_section;
        }
      else
        (*offset)++;
    }

  return FALSE;
}

/* this is responsible for syncing the showing of a separator for a
 * single subsection (and its children).
 *
 * we only ever show separators if we have _actual_ children (ie: we do
 * not show a separator if the section contains only empty child
 * sections).  it's difficult to determine this on-the-fly, so we have
 * this separate function to come back later and figure it out.
 *
 * 'section' is that section.
 *
 * 'tracker' is passed in so that we can emit callbacks when we decide
 * to add/remove separators.
 *
 * 'offset' is passed in so we know which position to emit in our
 * callbacks.  ie: if we add a separator right at the top of this
 * section then we would emit it with this offset.  deeper inside, we
 * adjust accordingly.
 *
 * could_have_separator is true in two situations:
 *
 *  - our parent section had with_separators defined and we are not the
 *    first section (ie: we should add a separator if we have content in
 *    order to divide us from the items above)
 *
 *  - if we had a 'label' attribute set for this section
 *
 * parent_model and parent_index are passed in so that we can give them
 * to the insertion callback so that it can see the label (and anything
 * else that happens to be defined on the section).
 *
 * we iterate each item in ourselves.  for subsections, we recursively
 * run ourselves to sync separators.  after we are done, we notice if we
 * have any items in us or if we are completely empty and sync if our
 * separator is shown or not.
 */
static gint
gtk_menu_tracker_section_sync_separators (GtkMenuTrackerSection *section,
                                          GtkMenuTracker        *tracker,
                                          gint                   offset,
                                          gboolean               could_have_separator,
                                          GMenuModel            *parent_model,
                                          gint                   parent_index)
{
  gboolean should_have_separator;
  gint n_items = 0;
  GSList *item;
  gint i = 0;

  for (item = section->items; item; item = item->next)
    {
      GtkMenuTrackerSection *subsection = item->data;

      if (subsection)
        {
          gboolean could_have_separator;

          could_have_separator = (section->with_separators && i > 0) ||
                                 g_menu_model_get_item_attribute (section->model, i, "label", "s", NULL);

          n_items += gtk_menu_tracker_section_sync_separators (subsection, tracker, offset + n_items,
                                                               could_have_separator, section->model, i);
        }
      else
        n_items++;

      i++;
    }

  should_have_separator = could_have_separator && n_items != 0;

  if (should_have_separator > section->has_separator)
    {
      /* Add a separator */
      GtkMenuTrackerItem *item;

      item = _gtk_menu_tracker_item_new (tracker->observable, parent_model, parent_index, NULL, TRUE);
      (* tracker->insert_func) (item, offset, tracker->user_data);
      g_object_unref (item);

      section->has_separator = TRUE;
    }
  else if (should_have_separator < section->has_separator)
    {
      /* Remove a separator */
      (* tracker->remove_func) (offset, tracker->user_data);
      section->has_separator = FALSE;
    }

  n_items += section->has_separator;

  return n_items;
}

static gint
gtk_menu_tracker_section_measure (GtkMenuTrackerSection *section)
{
  GSList *item;
  gint n_items;

  if (section == NULL)
    return 1;

  n_items = 0;

  if (section->has_separator)
    n_items++;

  for (item = section->items; item; item = item->next)
    n_items += gtk_menu_tracker_section_measure (item->data);

  return n_items;
}

static void
gtk_menu_tracker_remove_items (GtkMenuTracker  *tracker,
                               GSList         **change_point,
                               gint             offset,
                               gint             n_items)
{
  gint i;

  for (i = 0; i < n_items; i++)
    {
      GtkMenuTrackerSection *subsection;
      gint n;

      subsection = (*change_point)->data;
      *change_point = g_slist_delete_link (*change_point, *change_point);

      n = gtk_menu_tracker_section_measure (subsection);
      gtk_menu_tracker_section_free (subsection);

      while (n--)
        (* tracker->remove_func) (offset, tracker->user_data);
    }
}

static void
gtk_menu_tracker_add_items (GtkMenuTracker         *tracker,
                            GtkMenuTrackerSection  *section,
                            GSList                **change_point,
                            gint                    offset,
                            GMenuModel             *model,
                            gint                    position,
                            gint                    n_items)
{
  while (n_items--)
    {
      GMenuModel *submenu;

      submenu = g_menu_model_get_item_link (model, position + n_items, G_MENU_LINK_SECTION);
      g_assert (submenu != model);
      if (submenu != NULL)
        {
          GtkMenuTrackerSection *subsection;
          gchar *action_namespace = NULL;

          g_menu_model_get_item_attribute (model, position + n_items,
                                           G_MENU_ATTRIBUTE_ACTION_NAMESPACE, "s", &action_namespace);

          if (section->action_namespace)
            {
              gchar *namespace;

              namespace = g_strjoin (".", section->action_namespace, action_namespace, NULL);
              subsection = gtk_menu_tracker_section_new (tracker, submenu, FALSE, offset, namespace);
              g_free (namespace);
            }
          else
            subsection = gtk_menu_tracker_section_new (tracker, submenu, FALSE, offset, section->action_namespace);

          *change_point = g_slist_prepend (*change_point, subsection);
          g_free (action_namespace);
          g_object_unref (submenu);
        }
      else
        {
          GtkMenuTrackerItem *item;

          item = _gtk_menu_tracker_item_new (tracker->observable, model, position + n_items,
                                             section->action_namespace, FALSE);
          (* tracker->insert_func) (item, offset, tracker->user_data);
          g_object_unref (item);

          *change_point = g_slist_prepend (*change_point, NULL);
        }
    }
}

static void
gtk_menu_tracker_model_changed (GMenuModel *model,
                                gint        position,
                                gint        removed,
                                gint        added,
                                gpointer    user_data)
{
  GtkMenuTracker *tracker = user_data;
  GtkMenuTrackerSection *section;
  GSList **change_point;
  gint offset = 0;
  gint i;

  /* First find which section the changed model corresponds to, and the
   * position of that section within the overall menu.
   */
  section = gtk_menu_tracker_section_find_model (tracker->toplevel, model, &offset);

  /* Next, seek through that section to the change point.  This gives us
   * the correct GSList** to make the change to and also finds the final
   * offset at which we will make the changes (by measuring the number
   * of items within each item of the section before the change point).
   */
  change_point = &section->items;
  for (i = 0; i < position; i++)
    {
      offset += gtk_menu_tracker_section_measure ((*change_point)->data);
      change_point = &(*change_point)->next;
    }

  /* We remove items in order and add items in reverse order.  This
   * means that the offset used for all inserts and removes caused by a
   * single change will be the same.
   *
   * This also has a performance advantage: GtkMenuShell stores the
   * menu items in a linked list.  In the case where we are creating a
   * menu for the first time, adding the items in reverse order means
   * that we only ever insert at index zero, prepending the list.  This
   * means that we can populate in O(n) time instead of O(n^2) that we
   * would do by appending.
   */
  gtk_menu_tracker_remove_items (tracker, change_point, offset, removed);
  gtk_menu_tracker_add_items (tracker, section, change_point, offset, model, position, added);

  /* The offsets for insertion/removal of separators will be all over
   * the place, however...
   */
  gtk_menu_tracker_section_sync_separators (tracker->toplevel, tracker, 0, FALSE, NULL, 0);
}

static void
gtk_menu_tracker_section_free (GtkMenuTrackerSection *section)
{
  if (section == NULL)
    return;

  g_signal_handler_disconnect (section->model, section->handler);
  g_slist_free_full (section->items, (GDestroyNotify) gtk_menu_tracker_section_free);
  g_free (section->action_namespace);
  g_object_unref (section->model);
  g_slice_free (GtkMenuTrackerSection, section);
}

static GtkMenuTrackerSection *
gtk_menu_tracker_section_new (GtkMenuTracker *tracker,
                              GMenuModel     *model,
                              gboolean        with_separators,
                              gint            offset,
                              const gchar    *action_namespace)
{
  GtkMenuTrackerSection *section;

  section = g_slice_new0 (GtkMenuTrackerSection);
  section->model = g_object_ref (model);
  section->with_separators = with_separators;
  section->action_namespace = g_strdup (action_namespace);

  gtk_menu_tracker_add_items (tracker, section, &section->items, offset, model, 0, g_menu_model_get_n_items (model));
  section->handler = g_signal_connect (model, "items-changed", G_CALLBACK (gtk_menu_tracker_model_changed), tracker);

  return section;
}

/*< private >
 * gtk_menu_tracker_new:
 * @model: the model to flatten
 * @with_separators: if the toplevel should have separators (ie: TRUE
 *   for menus, FALSE for menubars)
 * @action_namespace: the passed-in action namespace
 * @insert_func: insert callback
 * @remove_func: remove callback
 * @user_data user data for callbacks
 *
 * Creates a GtkMenuTracker for @model, holding a ref on @model for as
 * long as the tracker is alive.
 *
 * This flattens out the model, merging sections and inserting
 * separators where appropriate.  It monitors for changes and performs
 * updates on the fly.  It also handles action_namespace for subsections
 * (but you will need to handle it yourself for submenus).
 *
 * When the tracker is first created, @insert_func will be called many
 * times to populate the menu with the initial contents of @model
 * (unless it is empty), before gtk_menu_tracker_new() returns.  For
 * this reason, the menu that is using the tracker ought to be empty
 * when it creates the tracker.
 *
 * Future changes to @model will result in more calls to @insert_func
 * and @remove_func.
 *
 * The position argument to both functions is the linear 0-based
 * position in the menu at which the item in question should be inserted
 * or removed.
 *
 * For @insert_func, @model and @item_index are used to get the
 * information about the menu item to insert.  @action_namespace is the
 * action namespace that actions referred to from that item should place
 * themselves in.  Note that if the item is a submenu and the
 * "action-namespace" attribute is defined on the item, it will _not_ be
 * applied to the @action_namespace argument as it is meant for the
 * items inside of the submenu, not the submenu item itself.
 *
 * @is_separator is set to %TRUE in case the item being added is a
 * separator.  @model and @item_index will still be meaningfully set in
 * this case -- to the section menu item corresponding to the separator.
 * This is useful if the section specifies a label, for example.  If
 * there is an "action-namespace" attribute on this menu item then it
 * should be ignored by the consumer because #GtkMenuTracker has already
 * handled it.
 *
 * When using #GtkMenuTracker there is no need to hold onto @model or
 * monitor it for changes.  The model will be unreffed when
 * gtk_menu_tracker_free() is called.
 */
GtkMenuTracker *
gtk_menu_tracker_new (GtkActionObservable      *observable,
                      GMenuModel               *model,
                      gboolean                  with_separators,
                      const gchar              *action_namespace,
                      GtkMenuTrackerInsertFunc  insert_func,
                      GtkMenuTrackerRemoveFunc  remove_func,
                      gpointer                  user_data)
{
  GtkMenuTracker *tracker;

  tracker = g_slice_new (GtkMenuTracker);
  tracker->observable = g_object_ref (observable);
  tracker->insert_func = insert_func;
  tracker->remove_func = remove_func;
  tracker->user_data = user_data;

  tracker->toplevel = gtk_menu_tracker_section_new (tracker, model, with_separators, 0, action_namespace);
  gtk_menu_tracker_section_sync_separators (tracker->toplevel, tracker, 0, FALSE, NULL, 0);

  return tracker;
}

GtkMenuTracker *
gtk_menu_tracker_new_for_item_submenu (GtkMenuTrackerItem       *item,
                                       GtkMenuTrackerInsertFunc  insert_func,
                                       GtkMenuTrackerRemoveFunc  remove_func,
                                       gpointer                  user_data)
{
  return gtk_menu_tracker_new (_gtk_menu_tracker_item_get_observable (item),
                               _gtk_menu_tracker_item_get_submenu (item),
                               TRUE,
                               _gtk_menu_tracker_item_get_submenu_namespace (item),
                               insert_func, remove_func, user_data);
}

/*< private >
 * gtk_menu_tracker_free:
 * @tracker: a #GtkMenuTracker
 *
 * Frees the tracker, ...
 */
void
gtk_menu_tracker_free (GtkMenuTracker *tracker)
{
  gtk_menu_tracker_section_free (tracker->toplevel);
  g_object_unref (tracker->observable);
  g_slice_free (GtkMenuTracker, tracker);
}