1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
//
// Copyright(C) 2005-2014 Simon Howard
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
//
// This program 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 General Public License for more details.
//
#ifndef TXT_WINDOW_H
#define TXT_WINDOW_H
/**
* @file txt_window.h
*
* Windows.
*/
/**
* A window.
*
* A window contains widgets, and may also be treated as a table
* (@ref txt_table_t) containing a single column.
*
* Windows can be created using @ref TXT_NewWindow and closed using
* @ref TXT_CloseWindow. When a window is closed, it emits the
* "closed" signal.
*
* In addition to the widgets within a window, windows also have
* a "tray" area at their bottom containing window action widgets.
* These widgets allow keyboard shortcuts to trigger common actions.
* Each window has three slots for keyboard shortcuts. By default,
* the left slot contains an action to close the window when the
* escape button is pressed, while the right slot contains an
* action to activate the currently-selected widget.
*/
typedef struct txt_window_s txt_window_t;
#include "txt_widget.h"
#include "txt_table.h"
#include "txt_window_action.h"
// Callback function for window key presses
typedef int (*TxtWindowKeyPress)(txt_window_t *window, int key,
void *user_data);
typedef int (*TxtWindowMousePress)(txt_window_t *window,
int x, int y, int b,
void *user_data);
struct txt_window_s
{
// Base class: all windows are tables with one column.
txt_table_t table;
// Window title
char *title;
// Screen coordinates of the window
txt_vert_align_t vert_align;
txt_horiz_align_t horiz_align;
int x, y;
// Actions that appear in the box at the bottom of the window
txt_widget_t *actions[3];
// Callback functions to invoke when keys/mouse buttons are pressed
TxtWindowKeyPress key_listener;
void *key_listener_data;
TxtWindowMousePress mouse_listener;
void *mouse_listener_data;
// These are set automatically when the window is drawn
int window_x, window_y;
unsigned int window_w, window_h;
// URL of a webpage with help about this window. If set, a help key
// indicator is shown while this window is active.
const char *help_url;
};
/**
* Open a new window.
*
* @param title Title to display in the titlebar of the new window
* (UTF-8 format).
* @return Pointer to a new @ref txt_window_t structure
* representing the new window.
*/
txt_window_t *TXT_NewWindow(const char *title);
/**
* Close a window.
*
* @param window Tine window to close.
*/
void TXT_CloseWindow(txt_window_t *window);
/**
* Set the position of a window on the screen.
*
* The position is specified as a pair of x, y, coordinates on the
* screen. These specify the position of a particular point on the
* window. The following are some examples:
*
* <code>
* // Centered on the screen:
*
* TXT_SetWindowPosition(window, TXT_HORIZ_CENTER, TXT_VERT_CENTER,
* TXT_SCREEN_W / 2, TXT_SCREEN_H / 2);
*
* // Horizontally centered, with top of the window on line 6:
*
* TXT_SetWindowPosition(window, TXT_HORIZ_CENTER, TXT_VERT_TOP,
* TXT_SCREEN_W / 2, 6);
*
* // Top-left of window at 20, 6:
*
* TXT_SetWindowPosition(window, TXT_HORIZ_LEFT, TXT_VERT_TOP, 20, 6);
* </code>
*
* @param window The window.
* @param horiz_align Horizontal location on the window for the X
* position.
* @param vert_align Vertical location on the window for the Y position.
* @param x X coordinate (horizontal axis) for window position.
* @param y Y coordinate (vertical axis) for window position.
*/
void TXT_SetWindowPosition(txt_window_t *window,
txt_horiz_align_t horiz_align,
txt_vert_align_t vert_align,
int x, int y);
/**
* Set a window action for a given window.
*
* Each window can have up to three window actions, which provide
* keyboard shortcuts that can be used within a given window.
*
* @param window The window.
* @param position The window action slot to set (left, center or right).
* @param action The window action widget. If this is NULL, any
* current window action in the given slot is removed.
*/
void TXT_SetWindowAction(txt_window_t *window, txt_horiz_align_t position,
TXT_UNCAST_ARG(action));
/**
* Set a callback function to be invoked whenever a key is pressed within
* a window.
*
* @param window The window.
* @param key_listener Callback function.
* @param user_data User-specified pointer to pass to the callback
* function.
*/
void TXT_SetKeyListener(txt_window_t *window,
TxtWindowKeyPress key_listener,
void *user_data);
/**
* Set a callback function to be invoked whenever a mouse button is pressed
* within a window.
*
* @param window The window.
* @param mouse_listener Callback function.
* @param user_data User-specified pointer to pass to the callback
* function.
*/
void TXT_SetMouseListener(txt_window_t *window,
TxtWindowMousePress mouse_listener,
void *user_data);
/**
* Open a window displaying a message.
*
* @param title Title of the window (UTF-8 format).
* @param message The message to display in the window (UTF-8 format).
* @return The new window.
*/
txt_window_t *TXT_MessageBox(const char *title, const char *message, ...);
/**
* Set the help URL for the given window.
*
* @param window The window.
* @param help_url String containing URL of the help page for this
* window, or NULL to set no help for this window.
*/
void TXT_SetWindowHelpURL(txt_window_t *window, const char *help_url);
/**
* Open the help URL for the given window, if one is set.
*
* @param window The window.
*/
void TXT_OpenWindowHelpURL(txt_window_t *window);
#endif /* #ifndef TXT_WINDOW_H */
|
