1/*
2 * GTK - The GIMP Toolkit
3 * Copyright (C) 1999 Red Hat, Inc.
4 * Copyright (C) 2002 Anders Carlsson <[email protected]>
5 * Copyright (C) 2003 Matthias Clasen <[email protected]>
6 * Copyright (C) 2005 Carlos Garnacho Parro <[email protected]>
7 *
8 * All rights reserved.
9 *
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2 of the License, or (at your option) any later version.
14 *
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
22 */
23
24#ifndef __GTK_ASSISTANT_H__
25#define __GTK_ASSISTANT_H__
26
27#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
28#error "Only <gtk/gtk.h> can be included directly."
29#endif
30
31#include <gtk/gtkwindow.h>
32
33G_BEGIN_DECLS
34
35#define GTK_TYPE_ASSISTANT (gtk_assistant_get_type ())
36#define GTK_ASSISTANT(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GTK_TYPE_ASSISTANT, GtkAssistant))
37#define GTK_ASSISTANT_CLASS(c) (G_TYPE_CHECK_CLASS_CAST ((c), GTK_TYPE_ASSISTANT, GtkAssistantClass))
38#define GTK_IS_ASSISTANT(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GTK_TYPE_ASSISTANT))
39#define GTK_IS_ASSISTANT_CLASS(c) (G_TYPE_CHECK_CLASS_TYPE ((c), GTK_TYPE_ASSISTANT))
40#define GTK_ASSISTANT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_ASSISTANT, GtkAssistantClass))
41
42/**
43 * GtkAssistantPageType:
44 * @GTK_ASSISTANT_PAGE_CONTENT: The page has regular contents. Both the
45 * Back and forward buttons will be shown.
46 * @GTK_ASSISTANT_PAGE_INTRO: The page contains an introduction to the
47 * assistant task. Only the Forward button will be shown if there is a
48 * next page.
49 * @GTK_ASSISTANT_PAGE_CONFIRM: The page lets the user confirm or deny the
50 * changes. The Back and Apply buttons will be shown.
51 * @GTK_ASSISTANT_PAGE_SUMMARY: The page informs the user of the changes
52 * done. Only the Close button will be shown.
53 * @GTK_ASSISTANT_PAGE_PROGRESS: Used for tasks that take a long time to
54 * complete, blocks the assistant until the page is marked as complete.
55 * Only the back button will be shown.
56 * @GTK_ASSISTANT_PAGE_CUSTOM: Used for when other page types are not
57 * appropriate. No buttons will be shown, and the application must
58 * add its own buttons through gtk_assistant_add_action_widget().
59 *
60 * An enum for determining the page role inside the #GtkAssistant. It's
61 * used to handle buttons sensitivity and visibility.
62 *
63 * Note that an assistant needs to end its page flow with a page of type
64 * %GTK_ASSISTANT_PAGE_CONFIRM, %GTK_ASSISTANT_PAGE_SUMMARY or
65 * %GTK_ASSISTANT_PAGE_PROGRESS to be correct.
66 *
67 * The Cancel button will only be shown if the page isn’t “committed”.
68 * See gtk_assistant_commit() for details.
69 */
70typedef enum
71{
72 GTK_ASSISTANT_PAGE_CONTENT,
73 GTK_ASSISTANT_PAGE_INTRO,
74 GTK_ASSISTANT_PAGE_CONFIRM,
75 GTK_ASSISTANT_PAGE_SUMMARY,
76 GTK_ASSISTANT_PAGE_PROGRESS,
77 GTK_ASSISTANT_PAGE_CUSTOM
78} GtkAssistantPageType;
79
80typedef struct _GtkAssistant GtkAssistant;
81typedef struct _GtkAssistantPrivate GtkAssistantPrivate;
82typedef struct _GtkAssistantClass GtkAssistantClass;
83
84struct _GtkAssistant
85{
86 GtkWindow parent;
87
88 /*< private >*/
89 GtkAssistantPrivate *priv;
90};
91
92/**
93 * GtkAssistantClass:
94 * @parent_class: The parent class.
95 * @prepare: Signal emitted when a new page is set as the assistant’s current page, before making the new page visible.
96 * @apply: Signal emitted when the apply button is clicked.
97 * @close: Signal emitted either when the close button or last page apply button is clicked.
98 * @cancel: Signal emitted when the cancel button is clicked.
99 */
100struct _GtkAssistantClass
101{
102 GtkWindowClass parent_class;
103
104 /*< public >*/
105
106 void (* prepare) (GtkAssistant *assistant, GtkWidget *page);
107 void (* apply) (GtkAssistant *assistant);
108 void (* close) (GtkAssistant *assistant);
109 void (* cancel) (GtkAssistant *assistant);
110
111 /*< private >*/
112
113 /* Padding for future expansion */
114 void (*_gtk_reserved1) (void);
115 void (*_gtk_reserved2) (void);
116 void (*_gtk_reserved3) (void);
117 void (*_gtk_reserved4) (void);
118 void (*_gtk_reserved5) (void);
119};
120
121/**
122 * GtkAssistantPageFunc:
123 * @current_page: The page number used to calculate the next page.
124 * @data: (closure): user data.
125 *
126 * A function used by gtk_assistant_set_forward_page_func() to know which
127 * is the next page given a current one. It’s called both for computing the
128 * next page when the user presses the “forward” button and for handling
129 * the behavior of the “last” button.
130 *
131 * Returns: The next page number.
132 */
133typedef gint (*GtkAssistantPageFunc) (gint current_page, gpointer data);
134
135GDK_AVAILABLE_IN_ALL
136GType gtk_assistant_get_type (void) G_GNUC_CONST;
137GDK_AVAILABLE_IN_ALL
138GtkWidget *gtk_assistant_new (void);
139GDK_AVAILABLE_IN_ALL
140void gtk_assistant_next_page (GtkAssistant *assistant);
141GDK_AVAILABLE_IN_ALL
142void gtk_assistant_previous_page (GtkAssistant *assistant);
143GDK_AVAILABLE_IN_ALL
144gint gtk_assistant_get_current_page (GtkAssistant *assistant);
145GDK_AVAILABLE_IN_ALL
146void gtk_assistant_set_current_page (GtkAssistant *assistant,
147 gint page_num);
148GDK_AVAILABLE_IN_ALL
149gint gtk_assistant_get_n_pages (GtkAssistant *assistant);
150GDK_AVAILABLE_IN_ALL
151GtkWidget *gtk_assistant_get_nth_page (GtkAssistant *assistant,
152 gint page_num);
153GDK_AVAILABLE_IN_ALL
154gint gtk_assistant_prepend_page (GtkAssistant *assistant,
155 GtkWidget *page);
156GDK_AVAILABLE_IN_ALL
157gint gtk_assistant_append_page (GtkAssistant *assistant,
158 GtkWidget *page);
159GDK_AVAILABLE_IN_ALL
160gint gtk_assistant_insert_page (GtkAssistant *assistant,
161 GtkWidget *page,
162 gint position);
163GDK_AVAILABLE_IN_3_2
164void gtk_assistant_remove_page (GtkAssistant *assistant,
165 gint page_num);
166GDK_AVAILABLE_IN_ALL
167void gtk_assistant_set_forward_page_func (GtkAssistant *assistant,
168 GtkAssistantPageFunc page_func,
169 gpointer data,
170 GDestroyNotify destroy);
171GDK_AVAILABLE_IN_ALL
172void gtk_assistant_set_page_type (GtkAssistant *assistant,
173 GtkWidget *page,
174 GtkAssistantPageType type);
175GDK_AVAILABLE_IN_ALL
176GtkAssistantPageType gtk_assistant_get_page_type (GtkAssistant *assistant,
177 GtkWidget *page);
178GDK_AVAILABLE_IN_ALL
179void gtk_assistant_set_page_title (GtkAssistant *assistant,
180 GtkWidget *page,
181 const gchar *title);
182GDK_AVAILABLE_IN_ALL
183const gchar * gtk_assistant_get_page_title (GtkAssistant *assistant,
184 GtkWidget *page);
185
186GDK_DEPRECATED_IN_3_2
187void gtk_assistant_set_page_header_image (GtkAssistant *assistant,
188 GtkWidget *page,
189 GdkPixbuf *pixbuf);
190GDK_DEPRECATED_IN_3_2
191GdkPixbuf *gtk_assistant_get_page_header_image (GtkAssistant *assistant,
192 GtkWidget *page);
193GDK_DEPRECATED_IN_3_2
194void gtk_assistant_set_page_side_image (GtkAssistant *assistant,
195 GtkWidget *page,
196 GdkPixbuf *pixbuf);
197GDK_DEPRECATED_IN_3_2
198GdkPixbuf *gtk_assistant_get_page_side_image (GtkAssistant *assistant,
199 GtkWidget *page);
200
201GDK_AVAILABLE_IN_ALL
202void gtk_assistant_set_page_complete (GtkAssistant *assistant,
203 GtkWidget *page,
204 gboolean complete);
205GDK_AVAILABLE_IN_ALL
206gboolean gtk_assistant_get_page_complete (GtkAssistant *assistant,
207 GtkWidget *page);
208GDK_AVAILABLE_IN_ALL
209void gtk_assistant_add_action_widget (GtkAssistant *assistant,
210 GtkWidget *child);
211GDK_AVAILABLE_IN_ALL
212void gtk_assistant_remove_action_widget (GtkAssistant *assistant,
213 GtkWidget *child);
214
215GDK_AVAILABLE_IN_ALL
216void gtk_assistant_update_buttons_state (GtkAssistant *assistant);
217GDK_AVAILABLE_IN_ALL
218void gtk_assistant_commit (GtkAssistant *assistant);
219
220GDK_AVAILABLE_IN_3_18
221void gtk_assistant_set_page_has_padding (GtkAssistant *assistant,
222 GtkWidget *page,
223 gboolean has_padding);
224GDK_AVAILABLE_IN_3_18
225gboolean gtk_assistant_get_page_has_padding (GtkAssistant *assistant,
226 GtkWidget *page);
227
228G_END_DECLS
229
230#endif /* __GTK_ASSISTANT_H__ */
231