1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gtk.Statusbar;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Signals;
31 private import gtk.Widget;
32 private import gtk.c.functions;
33 public  import gtk.c.types;
34 private import std.algorithm;
35 
36 
37 /**
38  * A `GtkStatusbar` widget is usually placed along the bottom of an application's
39  * main [class@Gtk.Window].
40  * 
41  * ![An example GtkStatusbar](statusbar.png)
42  * 
43  * A `GtkStatusBar` may provide a regular commentary of the application's
44  * status (as is usually the case in a web browser, for example), or may be
45  * used to simply output a message when the status changes, (when an upload
46  * is complete in an FTP client, for example).
47  * 
48  * Status bars in GTK maintain a stack of messages. The message at
49  * the top of the each bar’s stack is the one that will currently be displayed.
50  * 
51  * Any messages added to a statusbar’s stack must specify a context id that
52  * is used to uniquely identify the source of a message. This context id can
53  * be generated by [method@Gtk.Statusbar.get_context_id], given a message and
54  * the statusbar that it will be added to. Note that messages are stored in a
55  * stack, and when choosing which message to display, the stack structure is
56  * adhered to, regardless of the context identifier of a message.
57  * 
58  * One could say that a statusbar maintains one stack of messages for
59  * display purposes, but allows multiple message producers to maintain
60  * sub-stacks of the messages they produced (via context ids).
61  * 
62  * Status bars are created using [ctor@Gtk.Statusbar.new].
63  * 
64  * Messages are added to the bar’s stack with [method@Gtk.Statusbar.push].
65  * 
66  * The message at the top of the stack can be removed using
67  * [method@Gtk.Statusbar.pop]. A message can be removed from anywhere in the
68  * stack if its message id was recorded at the time it was added. This is done
69  * using [method@Gtk.Statusbar.remove].
70  * 
71  * ## CSS node
72  * 
73  * `GtkStatusbar` has a single CSS node with name `statusbar`.
74  */
75 public class Statusbar : Widget
76 {
77 	/** the main Gtk struct */
78 	protected GtkStatusbar* gtkStatusbar;
79 
80 	/** Get the main Gtk struct */
81 	public GtkStatusbar* getStatusbarStruct(bool transferOwnership = false)
82 	{
83 		if (transferOwnership)
84 			ownedRef = false;
85 		return gtkStatusbar;
86 	}
87 
88 	/** the main Gtk struct as a void* */
89 	protected override void* getStruct()
90 	{
91 		return cast(void*)gtkStatusbar;
92 	}
93 
94 	/**
95 	 * Sets our main struct and passes it to the parent class.
96 	 */
97 	public this (GtkStatusbar* gtkStatusbar, bool ownedRef = false)
98 	{
99 		this.gtkStatusbar = gtkStatusbar;
100 		super(cast(GtkWidget*)gtkStatusbar, ownedRef);
101 	}
102 
103 
104 	/** */
105 	public static GType getType()
106 	{
107 		return gtk_statusbar_get_type();
108 	}
109 
110 	/**
111 	 * Creates a new `GtkStatusbar` ready for messages.
112 	 *
113 	 * Returns: the new `GtkStatusbar`
114 	 *
115 	 * Throws: ConstructionException GTK+ fails to create the object.
116 	 */
117 	public this()
118 	{
119 		auto __p = gtk_statusbar_new();
120 
121 		if(__p is null)
122 		{
123 			throw new ConstructionException("null returned by new");
124 		}
125 
126 		this(cast(GtkStatusbar*) __p);
127 	}
128 
129 	/**
130 	 * Returns a new context identifier, given a description
131 	 * of the actual context.
132 	 *
133 	 * Note that the description is not shown in the UI.
134 	 *
135 	 * Params:
136 	 *     contextDescription = textual description of what context
137 	 *         the new message is being used in
138 	 *
139 	 * Returns: an integer id
140 	 */
141 	public uint getContextId(string contextDescription)
142 	{
143 		return gtk_statusbar_get_context_id(gtkStatusbar, Str.toStringz(contextDescription));
144 	}
145 
146 	/**
147 	 * Removes the first message in the `GtkStatusbar`’s stack
148 	 * with the given context id.
149 	 *
150 	 * Note that this may not change the displayed message,
151 	 * if the message at the top of the stack has a different
152 	 * context id.
153 	 *
154 	 * Params:
155 	 *     contextId = a context identifier
156 	 */
157 	public void pop(uint contextId)
158 	{
159 		gtk_statusbar_pop(gtkStatusbar, contextId);
160 	}
161 
162 	/**
163 	 * Pushes a new message onto a statusbar’s stack.
164 	 *
165 	 * Params:
166 	 *     contextId = the message’s context id, as returned by
167 	 *         gtk_statusbar_get_context_id()
168 	 *     text = the message to add to the statusbar
169 	 *
170 	 * Returns: a message id that can be used with
171 	 *     [method@Gtk.Statusbar.remove].
172 	 */
173 	public uint push(uint contextId, string text)
174 	{
175 		return gtk_statusbar_push(gtkStatusbar, contextId, Str.toStringz(text));
176 	}
177 
178 	/**
179 	 * Forces the removal of a message from a statusbar’s stack.
180 	 * The exact @context_id and @message_id must be specified.
181 	 *
182 	 * Params:
183 	 *     contextId = a context identifier
184 	 *     messageId = a message identifier, as returned by [method@Gtk.Statusbar.push]
185 	 */
186 	public void remove(uint contextId, uint messageId)
187 	{
188 		gtk_statusbar_remove(gtkStatusbar, contextId, messageId);
189 	}
190 
191 	/**
192 	 * Forces the removal of all messages from a statusbar's
193 	 * stack with the exact @context_id.
194 	 *
195 	 * Params:
196 	 *     contextId = a context identifier
197 	 */
198 	public void removeAll(uint contextId)
199 	{
200 		gtk_statusbar_remove_all(gtkStatusbar, contextId);
201 	}
202 
203 	/**
204 	 * Emitted whenever a new message is popped off a statusbar's stack.
205 	 *
206 	 * Params:
207 	 *     contextId = the context id of the relevant message/statusbar
208 	 *     text = the message that was just popped
209 	 */
210 	gulong addOnTextPopped(void delegate(uint, string, Statusbar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
211 	{
212 		return Signals.connect(this, "text-popped", dlg, connectFlags ^ ConnectFlags.SWAPPED);
213 	}
214 
215 	/**
216 	 * Emitted whenever a new message gets pushed onto a statusbar's stack.
217 	 *
218 	 * Params:
219 	 *     contextId = the context id of the relevant message/statusbar
220 	 *     text = the message that was pushed
221 	 */
222 	gulong addOnTextPushed(void delegate(uint, string, Statusbar) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
223 	{
224 		return Signals.connect(this, "text-pushed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
225 	}
226 }