txt_window.h 6.56 KB
Newer Older
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
//
// 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

75
    txt_widget_t *actions[3];
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90

    // 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.
91
    const char *help_url;
92 93 94 95 96 97 98 99 100 101 102
};

/**
 * 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.
 */

103
txt_window_t *TXT_NewWindow(const char *title);
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

/**
 * 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,
162
                         TXT_UNCAST_ARG(action));
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

/**
 * 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.
 */

200
txt_window_t *TXT_MessageBox(const char *title, const char *message, ...);
201 202 203 204 205 206 207 208 209

/**
 * 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.
 */

210
void TXT_SetWindowHelpURL(txt_window_t *window, const char *help_url);
211 212 213 214 215 216 217 218 219 220 221

/**
 * 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 */