gtkstatusbar.c 14.3 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GTK - The GIMP Toolkit
Shawn Amundson's avatar
Shawn Amundson committed
2 3 4 5
 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
 * GtkStatusbar Copyright (C) 1998 Shawn T. Amundson
 *
 * This library is free software; you can redistribute it and/or
6
 * modify it under the terms of the GNU Lesser General Public
Shawn Amundson's avatar
Shawn Amundson committed
7 8 9 10 11 12
 * License as published by the Free Software Foundation; either
 * version 2 of the License, 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
13
 * Lesser General Public License for more details.
Shawn Amundson's avatar
Shawn Amundson committed
14
 *
15
 * You should have received a copy of the GNU Lesser General Public
Javier Jardón's avatar
Javier Jardón committed
16
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
Shawn Amundson's avatar
Shawn Amundson committed
17 18
 */

19
/*
20
 * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
21 22
 * file for a list of people on the GTK+ Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
23
 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
24 25
 */

26
#include "config.h"
27

28 29 30
#include "gtkstatusbar.h"

#include "gtkboxprivate.h"
Shawn Amundson's avatar
Shawn Amundson committed
31 32
#include "gtkframe.h"
#include "gtklabel.h"
33
#include "gtkmarshalers.h"
Owen Taylor's avatar
Owen Taylor committed
34
#include "gtkwindow.h"
35
#include "gtkprivate.h"
36
#include "gtkintl.h"
37
#include "gtkorientable.h"
38
#include "gtktypebuiltins.h"
39
#include "a11y/gtkstatusbaraccessible.h"
Shawn Amundson's avatar
Shawn Amundson committed
40

41 42 43 44 45 46 47 48 49 50 51 52
/**
 * SECTION:gtkstatusbar
 * @title: GtkStatusbar
 * @short_description: Report messages of minor importance to the user
 *
 * A #GtkStatusbar is usually placed along the bottom of an application's
 * main #GtkWindow. It may provide a regular commentary of the application's
 * status (as is usually the case in a web browser, for example), or may be
 * used to simply output a message when the status changes, (when an upload
 * is complete in an FTP client, for example).
 *
 * Status bars in GTK+ maintain a stack of messages. The message at
53
 * the top of the each bar’s stack is the one that will currently be displayed.
54
 *
55
 * Any messages added to a statusbar’s stack must specify a
56
 * context id that is used to uniquely identify
57 58 59 60 61 62 63 64 65 66 67 68
 * the source of a message. This context id can be generated by
 * gtk_statusbar_get_context_id(), given a message and the statusbar that
 * it will be added to. Note that messages are stored in a stack, and when
 * choosing which message to display, the stack structure is adhered to,
 * regardless of the context identifier of a message.
 *
 * One could say that a statusbar maintains one stack of messages for
 * display purposes, but allows multiple message producers to maintain
 * sub-stacks of the messages they produced (via context ids).
 *
 * Status bars are created using gtk_statusbar_new().
 *
69
 * Messages are added to the bar’s stack with gtk_statusbar_push().
70 71 72 73 74
 *
 * The message at the top of the stack can be removed using
 * gtk_statusbar_pop(). A message can be removed from anywhere in the
 * stack if its message id was recorded at the time it was added. This
 * is done using gtk_statusbar_remove().
75 76 77 78
 *
 * # CSS node
 *
 * GtkStatusbar has a single CSS node with name statusbar.
79
 */
80

81 82
typedef struct _GtkStatusbarMsg GtkStatusbarMsg;

83
struct _GtkStatusbarPrivate
84 85 86
{
  GtkWidget     *frame;
  GtkWidget     *label;
87
  GtkWidget     *message_area;
88 89 90 91 92 93 94 95 96

  GSList        *messages;
  GSList        *keys;

  guint          seq_context_id;
  guint          seq_message_id;
};


97 98 99 100 101 102
struct _GtkStatusbarMsg
{
  gchar *text;
  guint context_id;
  guint message_id;
};
103 104 105 106 107 108 109 110

enum
{
  SIGNAL_TEXT_PUSHED,
  SIGNAL_TEXT_POPPED,
  SIGNAL_LAST
};

111 112 113
static void     gtk_statusbar_update            (GtkStatusbar      *statusbar,
						 guint              context_id,
						 const gchar       *text);
114
static void     gtk_statusbar_destroy           (GtkWidget         *widget);
Owen Taylor's avatar
Owen Taylor committed
115

116
static guint              statusbar_signals[SIGNAL_LAST] = { 0 };
Shawn Amundson's avatar
Shawn Amundson committed
117

118
G_DEFINE_TYPE_WITH_PRIVATE (GtkStatusbar, gtk_statusbar, GTK_TYPE_BOX)
Shawn Amundson's avatar
Shawn Amundson committed
119 120 121 122

static void
gtk_statusbar_class_init (GtkStatusbarClass *class)
{
123
  GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (class);
Shawn Amundson's avatar
Shawn Amundson committed
124

125
  widget_class->destroy = gtk_statusbar_destroy;
126

127 128
  class->text_pushed = gtk_statusbar_update;
  class->text_popped = gtk_statusbar_update;
129

Matthias Clasen's avatar
Matthias Clasen committed
130
  /**
131
   * GtkStatusbar::text-pushed:
Matthias Clasen's avatar
Matthias Clasen committed
132 133 134 135
   * @statusbar: the object which received the signal
   * @context_id: the context id of the relevant message/statusbar
   * @text: the message that was pushed
   *
136 137
   * Is emitted whenever a new message gets pushed onto a statusbar's stack.
   */
138
  statusbar_signals[SIGNAL_TEXT_PUSHED] =
139
    g_signal_new (I_("text-pushed"),
Manish Singh's avatar
Manish Singh committed
140 141 142 143 144 145 146 147
		  G_OBJECT_CLASS_TYPE (class),
		  G_SIGNAL_RUN_LAST,
		  G_STRUCT_OFFSET (GtkStatusbarClass, text_pushed),
		  NULL, NULL,
		  _gtk_marshal_VOID__UINT_STRING,
		  G_TYPE_NONE, 2,
		  G_TYPE_UINT,
		  G_TYPE_STRING);
148 149 150

  /**
   * GtkStatusbar::text-popped:
Matthias Clasen's avatar
Matthias Clasen committed
151 152 153
   * @statusbar: the object which received the signal
   * @context_id: the context id of the relevant message/statusbar
   * @text: the message that was just popped
154 155 156
   *
   * Is emitted whenever a new message is popped off a statusbar's stack.
   */
157
  statusbar_signals[SIGNAL_TEXT_POPPED] =
158
    g_signal_new (I_("text-popped"),
Manish Singh's avatar
Manish Singh committed
159 160 161 162 163 164 165 166
		  G_OBJECT_CLASS_TYPE (class),
		  G_SIGNAL_RUN_LAST,
		  G_STRUCT_OFFSET (GtkStatusbarClass, text_popped),
		  NULL, NULL,
		  _gtk_marshal_VOID__UINT_STRING,
		  G_TYPE_NONE, 2,
		  G_TYPE_UINT,
		  G_TYPE_STRING);
167

168 169 170 171 172 173 174 175
  /**
   * GtkStatusbar:shadow-type:
   *
   * The style of the bevel around the statusbar text.
   *
   * Deprecated: 3.20: Use CSS properties to determine the appearance,
   *    the value of this style property is ignored.
   */
176
  gtk_widget_class_install_style_property (widget_class,
177
                                           g_param_spec_enum ("shadow-type",
178 179
                                                              P_("Shadow type"),
                                                              P_("Style of bevel around the statusbar text"),
180 181
                                                              GTK_TYPE_SHADOW_TYPE,
                                                              GTK_SHADOW_IN,
182
                                                              GTK_PARAM_READABLE|G_PARAM_DEPRECATED));
183

184 185
  /* Bind class to template
   */
186
  gtk_widget_class_set_template_from_resource (widget_class, "/org/gtk/libgtk/ui/gtkstatusbar.ui");
187 188 189
  gtk_widget_class_bind_template_child_internal_private (widget_class, GtkStatusbar, message_area);
  gtk_widget_class_bind_template_child_private (widget_class, GtkStatusbar, frame);
  gtk_widget_class_bind_template_child_private (widget_class, GtkStatusbar, label);
190 191

  gtk_widget_class_set_accessible_type (widget_class, GTK_TYPE_STATUSBAR_ACCESSIBLE);
192
  gtk_widget_class_set_css_name (widget_class, "statusbar");
Shawn Amundson's avatar
Shawn Amundson committed
193 194 195 196 197
}

static void
gtk_statusbar_init (GtkStatusbar *statusbar)
{
198
  GtkStatusbarPrivate *priv;
199

200
  statusbar->priv = gtk_statusbar_get_instance_private (statusbar);
201
  priv = statusbar->priv;
202

203 204 205 206
  priv->seq_context_id = 1;
  priv->seq_message_id = 1;
  priv->messages = NULL;
  priv->keys = NULL;
207

208 209
  gtk_widget_init_template (GTK_WIDGET (statusbar));
  gtk_widget_set_redraw_on_allocate (GTK_WIDGET (statusbar), TRUE);
210 211
}

212 213 214 215 216 217 218
/**
 * gtk_statusbar_new:
 *
 * Creates a new #GtkStatusbar ready for messages.
 *
 * Returns: the new #GtkStatusbar
 */
Shawn Amundson's avatar
Shawn Amundson committed
219
GtkWidget* 
220
gtk_statusbar_new (void)
Shawn Amundson's avatar
Shawn Amundson committed
221
{
Manish Singh's avatar
Manish Singh committed
222
  return g_object_new (GTK_TYPE_STATUSBAR, NULL);
223 224 225 226
}

static void
gtk_statusbar_update (GtkStatusbar *statusbar,
227
		      guint	    context_id,
228 229
		      const gchar  *text)
{
230
  GtkStatusbarPrivate *priv;
231

232
  g_return_if_fail (GTK_IS_STATUSBAR (statusbar));
Shawn Amundson's avatar
Shawn Amundson committed
233

234 235
  priv = statusbar->priv;

236 237
  if (!text)
    text = "";
Shawn Amundson's avatar
Shawn Amundson committed
238

239
  gtk_label_set_text (GTK_LABEL (priv->label), text);
Shawn Amundson's avatar
Shawn Amundson committed
240 241
}

242 243 244 245 246 247 248 249
/**
 * gtk_statusbar_get_context_id:
 * @statusbar: a #GtkStatusbar
 * @context_description: textual description of what context 
 *                       the new message is being used in
 *
 * Returns a new context identifier, given a description 
 * of the actual context. Note that the description is 
250
 * not shown in the UI.
251 252 253
 *
 * Returns: an integer id
 */
254 255 256 257
guint
gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
			      const gchar  *context_description)
{
258
  GtkStatusbarPrivate *priv;
259
  gchar *string;
Yevgen Muntyan's avatar
Yevgen Muntyan committed
260
  guint id;
261 262 263 264
  
  g_return_val_if_fail (GTK_IS_STATUSBAR (statusbar), 0);
  g_return_val_if_fail (context_description != NULL, 0);

265 266
  priv = statusbar->priv;

267 268 269
  /* we need to preserve namespaces on object datas */
  string = g_strconcat ("gtk-status-bar-context:", context_description, NULL);

270 271
  id = GPOINTER_TO_UINT (g_object_get_data (G_OBJECT (statusbar), string));
  if (id == 0)
272
    {
273
      id = priv->seq_context_id++;
274
      g_object_set_data_full (G_OBJECT (statusbar), string, GUINT_TO_POINTER (id), NULL);
275
      priv->keys = g_slist_prepend (priv->keys, string);
276 277 278 279
    }
  else
    g_free (string);

280
  return id;
281 282
}

Paolo Borelli's avatar
Paolo Borelli committed
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304
static GtkStatusbarMsg *
gtk_statusbar_msg_create (GtkStatusbar *statusbar,
		          guint         context_id,
		          const gchar  *text)
{
  GtkStatusbarMsg *msg;

  msg = g_slice_new (GtkStatusbarMsg);
  msg->text = g_strdup (text);
  msg->context_id = context_id;
  msg->message_id = statusbar->priv->seq_message_id++;

  return msg;
}

static void
gtk_statusbar_msg_free (GtkStatusbarMsg *msg)
{
  g_free (msg->text);
  g_slice_free (GtkStatusbarMsg, msg);
}

305 306 307
/**
 * gtk_statusbar_push:
 * @statusbar: a #GtkStatusbar
308
 * @context_id: the message’s context id, as returned by
309 310 311
 *              gtk_statusbar_get_context_id()
 * @text: the message to add to the statusbar
 * 
312
 * Pushes a new message onto a statusbar’s stack.
313 314 315 316
 *
 * Returns: a message id that can be used with 
 *          gtk_statusbar_remove().
 */
317 318
guint
gtk_statusbar_push (GtkStatusbar *statusbar,
319
		    guint	  context_id,
320
		    const gchar  *text)
Shawn Amundson's avatar
Shawn Amundson committed
321
{
322
  GtkStatusbarPrivate *priv;
Shawn Amundson's avatar
Shawn Amundson committed
323
  GtkStatusbarMsg *msg;
324 325 326

  g_return_val_if_fail (GTK_IS_STATUSBAR (statusbar), 0);
  g_return_val_if_fail (text != NULL, 0);
Shawn Amundson's avatar
Shawn Amundson committed
327

328 329
  priv = statusbar->priv;

Paolo Borelli's avatar
Paolo Borelli committed
330
  msg = gtk_statusbar_msg_create (statusbar, context_id, text);
331
  priv->messages = g_slist_prepend (priv->messages, msg);
Shawn Amundson's avatar
Shawn Amundson committed
332

Manish Singh's avatar
Manish Singh committed
333 334 335 336 337
  g_signal_emit (statusbar,
		 statusbar_signals[SIGNAL_TEXT_PUSHED],
		 0,
		 msg->context_id,
		 msg->text);
Shawn Amundson's avatar
Shawn Amundson committed
338

339
  return msg->message_id;
Shawn Amundson's avatar
Shawn Amundson committed
340 341
}

342 343
/**
 * gtk_statusbar_pop:
344
 * @statusbar: a #GtkStatusbar
345 346
 * @context_id: a context identifier
 * 
347
 * Removes the first message in the #GtkStatusbar’s stack
348 349 350 351 352 353
 * with the given context id. 
 *
 * Note that this may not change the displayed message, if 
 * the message at the top of the stack has a different 
 * context id.
 */
354
void
355 356
gtk_statusbar_pop (GtkStatusbar *statusbar,
		   guint	 context_id)
Shawn Amundson's avatar
Shawn Amundson committed
357
{
358
  GtkStatusbarPrivate *priv;
359
  GtkStatusbarMsg *msg;
Shawn Amundson's avatar
Shawn Amundson committed
360

361
  g_return_if_fail (GTK_IS_STATUSBAR (statusbar));
Shawn Amundson's avatar
Shawn Amundson committed
362

363 364 365
  priv = statusbar->priv;

  if (priv->messages)
366
    {
367
      GSList *list;
Owen Taylor's avatar
Owen Taylor committed
368

369
      for (list = priv->messages; list; list = list->next)
Owen Taylor's avatar
Owen Taylor committed
370 371 372 373 374
	{
	  msg = list->data;

	  if (msg->context_id == context_id)
	    {
Paolo Borelli's avatar
Paolo Borelli committed
375 376
	      priv->messages = g_slist_remove_link (priv->messages, list);
	      gtk_statusbar_msg_free (msg);
Owen Taylor's avatar
Owen Taylor committed
377 378 379 380
	      g_slist_free_1 (list);
	      break;
	    }
	}
381 382
    }

383
  msg = priv->messages ? priv->messages->data : NULL;
Shawn Amundson's avatar
Shawn Amundson committed
384

Manish Singh's avatar
Manish Singh committed
385 386 387 388 389
  g_signal_emit (statusbar,
		 statusbar_signals[SIGNAL_TEXT_POPPED],
		 0,
		 (guint) (msg ? msg->context_id : 0),
		 msg ? msg->text : NULL);
Shawn Amundson's avatar
Shawn Amundson committed
390 391
}

392 393
/**
 * gtk_statusbar_remove:
394
 * @statusbar: a #GtkStatusbar
395 396 397
 * @context_id: a context identifier
 * @message_id: a message identifier, as returned by gtk_statusbar_push()
 *
398
 * Forces the removal of a message from a statusbar’s stack. 
399 400
 * The exact @context_id and @message_id must be specified.
 */
Shawn Amundson's avatar
Shawn Amundson committed
401
void
402 403 404
gtk_statusbar_remove (GtkStatusbar *statusbar,
		      guint	   context_id,
		      guint        message_id)
Shawn Amundson's avatar
Shawn Amundson committed
405
{
406
  GtkStatusbarPrivate *priv;
407
  GtkStatusbarMsg *msg;
Shawn Amundson's avatar
Shawn Amundson committed
408

409
  g_return_if_fail (GTK_IS_STATUSBAR (statusbar));
410
  g_return_if_fail (message_id > 0);
Shawn Amundson's avatar
Shawn Amundson committed
411

412 413 414
  priv = statusbar->priv;

  msg = priv->messages ? priv->messages->data : NULL;
415 416
  if (msg)
    {
417 418 419 420 421
      GSList *list;

      /* care about signal emission if the topmost item is removed */
      if (msg->context_id == context_id &&
	  msg->message_id == message_id)
422
	{
423
	  gtk_statusbar_pop (statusbar, context_id);
424 425 426
	  return;
	}
      
427
      for (list = priv->messages; list; list = list->next)
428 429 430
	{
	  msg = list->data;
	  
431 432
	  if (msg->context_id == context_id &&
	      msg->message_id == message_id)
433
	    {
434
	      priv->messages = g_slist_remove_link (priv->messages, list);
Paolo Borelli's avatar
Paolo Borelli committed
435
	      gtk_statusbar_msg_free (msg);
436
	      g_slist_free_1 (list);
437 438 439 440
	      
	      break;
	    }
	}
Shawn Amundson's avatar
Shawn Amundson committed
441 442 443
    }
}

444 445
/**
 * gtk_statusbar_remove_all:
446
 * @statusbar: a #GtkStatusbar
447 448 449 450 451 452 453 454 455 456 457
 * @context_id: a context identifier
 *
 * Forces the removal of all messages from a statusbar's
 * stack with the exact @context_id.
 *
 * Since: 2.22
 */
void
gtk_statusbar_remove_all (GtkStatusbar *statusbar,
                          guint         context_id)
{
458
  GtkStatusbarPrivate *priv;
459 460 461 462 463
  GtkStatusbarMsg *msg;
  GSList *prev, *list;

  g_return_if_fail (GTK_IS_STATUSBAR (statusbar));

464 465 466
  priv = statusbar->priv;

  if (priv->messages == NULL)
467 468
    return;

469 470 471 472 473 474 475
  /* We special-case the topmost message at the bottom of this
   * function:
   * If we need to pop it, we have to update various state and we want
   * an up-to-date list of remaining messages in that case.
   */
  prev = priv->messages;
  list = prev->next;
476 477 478 479 480 481 482

  while (list != NULL)
    {
      msg = list->data;

      if (msg->context_id == context_id)
        {
483
          prev->next = list->next;
484

Paolo Borelli's avatar
Paolo Borelli committed
485
          gtk_statusbar_msg_free (msg);
486 487
          g_slist_free_1 (list);

488
          list = prev->next;
489 490 491 492 493 494 495
        }
      else
        {
          prev = list;
          list = prev->next;
        }
    }
496 497 498 499 500 501 502

  /* Treat topmost message here */
  msg = priv->messages->data;
  if (msg->context_id == context_id)
    {
      gtk_statusbar_pop (statusbar, context_id);
    }
503 504
}

505 506
/**
 * gtk_statusbar_get_message_area:
507
 * @statusbar: a #GtkStatusbar
508 509 510
 *
 * Retrieves the box containing the label widget.
 *
511
 * Returns: (type Gtk.Box) (transfer none): a #GtkBox
512 513 514 515 516 517
 *
 * Since: 2.20
 */
GtkWidget*
gtk_statusbar_get_message_area (GtkStatusbar *statusbar)
{
518
  GtkStatusbarPrivate *priv;
519

520 521
  g_return_val_if_fail (GTK_IS_STATUSBAR (statusbar), NULL);

522 523
  priv = statusbar->priv;

524
  return priv->message_area;
525 526
}

Shawn Amundson's avatar
Shawn Amundson committed
527
static void
528
gtk_statusbar_destroy (GtkWidget *widget)
Shawn Amundson's avatar
Shawn Amundson committed
529
{
530
  GtkStatusbar *statusbar = GTK_STATUSBAR (widget);
531
  GtkStatusbarPrivate *priv = statusbar->priv;
532

Paolo Borelli's avatar
Paolo Borelli committed
533
  g_slist_free_full (priv->messages, (GDestroyNotify) gtk_statusbar_msg_free);
534
  priv->messages = NULL;
Shawn Amundson's avatar
Shawn Amundson committed
535

Paolo Borelli's avatar
Paolo Borelli committed
536
  g_slist_free_full (priv->keys, g_free);
537
  priv->keys = NULL;
538

539
  GTK_WIDGET_CLASS (gtk_statusbar_parent_class)->destroy (widget);
540
}