1 /* SPDX-License-Identifier: Zlib */
2 
3 #ifndef GIRARA_SESSION_H
4 #define GIRARA_SESSION_H
5 
6 #include "types.h"
7 #include "macros.h"
8 #include "callbacks.h"
9 
10 #include <gtk/gtk.h>
11 
12 #ifdef GDK_WINDOWING_X11
13 #include <gtk/gtkx.h>
14 #else
15 typedef int Window;
16 #endif
17 
18 struct girara_session_s
19 {
20   struct
21   {
22     GtkWidget       *window; /**< The main window of the application */
23     GtkBox          *box; /**< A box that contains all widgets */
24     GtkWidget       *view; /**< The view area of the applications widgets */
25     GtkWidget       *viewport; /**< The viewport of view */
26     GtkWidget       *statusbar; /**< The statusbar */
27     GtkBox          *statusbar_entries; /**< Statusbar entry box */
28     GtkWidget       *notification_area; /**< The notification area */
29     GtkWidget       *notification_text; /**< The notification entry */
30     GtkBox          *inputbar_box; /**< Inputbar box */
31     GtkWidget       *inputbar; /**< Inputbar event box */
32     GtkLabel        *inputbar_dialog; /**< Inputbar dialog */
33     GtkEntry        *inputbar_entry; /**< Inputbar entry */
34     GtkBox          *results; /**< Completion results */
35     Window          embed; /**< Embedded window */
36   } gtk;
37 
38   struct
39   {
40     girara_list_t* mouse_events; /**< List of mouse events */
41     girara_list_t* commands; /**< List of commands */
42     girara_list_t* shortcuts; /**< List of shortcuts */
43     girara_list_t* special_commands; /**< List of special commands */
44     girara_list_t* inputbar_shortcuts; /**< List of inputbar shortcuts */
45   } bindings;
46 
47   struct
48   {
49     int inputbar_activate; /**< Inputbar activation */
50     int inputbar_key_pressed; /**< Pressed key in inputbar */
51     int inputbar_changed; /**< Inputbar text changed */
52     int view_key_pressed; /**< Pressed key in view */
53     int view_button_press_event; /**< Pressed button */
54     int view_button_release_event; /**< Released button */
55     int view_motion_notify_event; /**< Cursor movement event */
56     int view_scroll_event; /**< Scroll event */
57     girara_callback_inputbar_activate_t inputbar_custom_activate; /**< Custom handler */
58     girara_callback_inputbar_key_press_event_t inputbar_custom_key_press_event; /**< Custom handler */
59     void* inputbar_custom_data; /**< Data for custom handler */
60   } signals;
61 
62   struct
63   {
64     void (*buffer_changed)(girara_session_t* session); /**< Buffer changed */
65     bool (*unknown_command)(girara_session_t* session, const char* input); /**< Unknown command */
66   } events;
67 
68   struct
69   {
70     GString *buffer; /**< Buffer */
71     void* data; /**< User data */
72     bool autohide_inputbar; /**< Auto-hide inputbar */
73     bool hide_statusbar; /**< Hide statusbar */
74   } global;
75 
76   struct
77   {
78     girara_mode_t current_mode; /**< Current mode */
79     girara_list_t *identifiers; /**< List of modes with its string identifiers */
80     girara_mode_t normal; /**< The normal mode */
81     girara_mode_t inputbar; /**< The inputbar mode */
82   } modes;
83 
84   GiraraInputHistory* command_history; /**< Command history */
85   girara_session_private_t* private_data; /**< Private data of a girara session */
86 };
87 
88 /**
89  * Creates a girara session
90  *
91  * @return A valid session object
92  * @return NULL when an error occurred
93  */
94 girara_session_t* girara_session_create(void) GIRARA_VISIBLE;
95 
96 /**
97  * Initializes an girara session
98  *
99  * @param session The used girara session
100  * @param appname Name of the session (can be NULL)
101  * @return TRUE No error occurred
102  * @return FALSE An error occurred
103  */
104 bool girara_session_init(girara_session_t* session, const char* appname) GIRARA_VISIBLE;
105 
106 /**
107  * Destroys an girara session
108  *
109  * @param session The used girara session
110  * @return TRUE No error occurred
111  * @return FALSE An error occurred
112  */
113 bool girara_session_destroy(girara_session_t* session) GIRARA_VISIBLE;
114 
115 /**
116  * Sets the view widget of girara
117  *
118  * @param session The used girara session
119  * @param widget The widget that should be displayed
120  * @return TRUE No error occurred
121  * @return FALSE An error occurred
122  */
123 bool girara_set_view(girara_session_t* session, GtkWidget* widget) GIRARA_VISIBLE;
124 
125 /**
126  * Returns a copy of the buffer
127  *
128  * @param session The used girara session
129  * @return Copy of the current buffer
130  */
131 char* girara_buffer_get(girara_session_t* session) GIRARA_VISIBLE;
132 
133 /**
134  * Displays a notification popup for the user using libnotify. Basic styling
135  * is allowed using Pango's markup format:
136  * <https://developer.gnome.org/pango/stable/PangoMarkupFormat.html>
137  *
138  * @param session The girara session
139  * @param summary The title
140  * @param body The content
141  */
142 void girara_libnotify(girara_session_t* session, const char *summary,
143     const char *body) GIRARA_VISIBLE;
144 
145 /**
146  * Displays a notification for the user. It is possible to pass GIRARA_INFO,
147  * GIRARA_WARNING or GIRARA_ERROR as a notification level.
148  *
149  * @param session The girara session
150  * @param level The level
151  * @param format String format
152  * @param ...
153  */
154 void girara_notify(girara_session_t* session, int level,
155     const char* format, ...) GIRARA_PRINTF(3, 4) GIRARA_VISIBLE;
156 
157 /**
158  * Creates a girara dialog
159  *
160  * @param session The girara session
161  * @param dialog The dialog message
162  * @param invisible Sets the input visibility
163  * @param key_press_event Callback function to a custom key press event handler
164  * @param activate_event Callback function to a custom activate event handler
165  * @param data Custom data that is passed to the callback functions
166  */
167 void girara_dialog(girara_session_t* session, const char* dialog, bool
168     invisible, girara_callback_inputbar_key_press_event_t key_press_event,
169     girara_callback_inputbar_activate_t activate_event, void* data) GIRARA_VISIBLE;
170 
171 /**
172  * Adds a new mode by its string identifier
173  *
174  * @param session The used girara session
175  * @param name The string identifier used in configs/inputbar etc to refer by
176  * @return A newly defined girara_mode_t associated with name
177  */
178 girara_mode_t girara_mode_add(girara_session_t* session, const char* name) GIRARA_VISIBLE;
179 
180 /**
181  * Sets the current mode
182  *
183  * @param session The used girara session
184  * @param mode The new mode
185  */
186 void girara_mode_set(girara_session_t* session, girara_mode_t mode) GIRARA_VISIBLE;
187 
188 /**
189  * Returns the current mode
190  *
191  * @param session The used girara session
192  * @return The current mode
193  */
194 girara_mode_t girara_mode_get(girara_session_t* session) GIRARA_VISIBLE;
195 
196 /**
197  * Set name of the window title
198  *
199  * @param session The used girara session
200  * @param name The new name of the session
201  * @return true if no error occurred
202  * @return false if an error occurred
203  */
204 bool girara_set_window_title(girara_session_t* session, const char* name) GIRARA_VISIBLE;
205 
206 /**
207  * Set icon of the window
208  *
209  * @param session The used girara session
210  * @param name the name of the themed icon
211  * @return true if no error occurred
212  * @return false if an error occurred
213  */
214 bool girara_set_window_icon(girara_session_t* session, const char* name) GIRARA_VISIBLE;
215 
216 /**
217  * Returns the command history
218  *
219  * @param session The used girara session
220  * @return The command history (list of strings) or NULL
221  */
222 girara_list_t* girara_get_command_history(girara_session_t* session) GIRARA_VISIBLE;
223 
224 /**
225  * Returns the internal template object to apply custom theming options
226  *
227  * @param session The girara session
228  * @returns GiraraTemplate object
229  */
230 GiraraTemplate* girara_session_get_template(girara_session_t* session) GIRARA_VISIBLE;
231 
232 /**
233  * Replaces the internal template object, thus provides entirely user-defined styling.
234  *
235  * @param session The girara session
236  * @param template The template to apply, @ref girara_template_new
237  * @param init_variables Defines whether the default variables and current
238  *    values should be added to the the template
239  *
240  * @note Using the template @c girara_template_new("") will use the default gtk style
241  *
242  */
243 void girara_session_set_template(girara_session_t* session, GiraraTemplate* template, bool init_variables) GIRARA_VISIBLE;
244 
245 #endif
246