gntentry.h

   1 /**
   2  * @file gntentry.h Entry API
   3  * @ingroup gnt
   4  */
   5 /*
   6  * GNT - The GLib Ncurses Toolkit
   7  *
   8  * GNT is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This library is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26
  27 #ifndef GNT_ENTRY_H
  28 #define GNT_ENTRY_H
  29
  30 #include "gntwidget.h"
  31 #include "gnt.h"
  32 #include "gntcolors.h"
  33 #include "gntkeys.h"
  34
  35 #define GNT_TYPE_ENTRY                          (gnt_entry_get_gtype())
  36 #define GNT_ENTRY(obj)                          (G_TYPE_CHECK_INSTANCE_CAST((obj), GNT_TYPE_ENTRY, GntEntry))
  37 #define GNT_ENTRY_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST((klass), GNT_TYPE_ENTRY, GntEntryClass))
  38 #define GNT_IS_ENTRY(obj)                       (G_TYPE_CHECK_INSTANCE_TYPE((obj), GNT_TYPE_ENTRY))
  39 #define GNT_IS_ENTRY_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE((klass), GNT_TYPE_ENTRY))
  40 #define GNT_ENTRY_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS((obj), GNT_TYPE_ENTRY, GntEntryClass))
  41
  42 #define GNT_ENTRY_FLAGS(obj)                            (GNT_ENTRY(obj)->priv.flags)
  43 #define GNT_ENTRY_SET_FLAGS(obj, flags)         (GNT_ENTRY_FLAGS(obj) |= flags)
  44 #define GNT_ENTRY_UNSET_FLAGS(obj, flags)       (GNT_ENTRY_FLAGS(obj) &= ~(flags))
  45
  46 #define ENTRY_CHAR              '_'                     /* The character to use to fill in the blank places */
  47
  48 typedef struct _GntEntry                        GntEntry;
  49 typedef struct _GntEntryPriv            GntEntryPriv;
  50 typedef struct _GntEntryClass   GntEntryClass;
  51 typedef struct _GntEntryKillRing    GntEntryKillRing;
  52
  53 typedef enum
  54 {
  55         GNT_ENTRY_FLAG_ALPHA    = 1 << 0,  /* Only alpha */
  56         GNT_ENTRY_FLAG_INT      = 1 << 1,  /* Only integer */
  57         GNT_ENTRY_FLAG_NO_SPACE = 1 << 2,  /* No blank space is allowed */
  58         GNT_ENTRY_FLAG_NO_PUNCT = 1 << 3,  /* No punctuations */
  59         GNT_ENTRY_FLAG_MASK     = 1 << 4,  /* Mask the inputs */
  60 } GntEntryFlag;
  61
  62 #define GNT_ENTRY_FLAG_ALL    (GNT_ENTRY_FLAG_ALPHA | GNT_ENTRY_FLAG_INT)
  63
  64 struct _GntEntry
  65 {
  66         GntWidget parent;
  67
  68         GntEntryFlag flag;
  69
  70         char *start;
  71         char *end;
  72         char *scroll;   /* Current scrolling position */
  73         char *cursor;   /* Cursor location */
  74                         /* 0 <= cursor - scroll < widget-width */
  75
  76         size_t buffer;  /* Size of the buffer */
  77
  78         int max;        /* 0 means infinite */
  79         gboolean masked;
  80
  81         GList *history; /* History of the strings. User can use this by pressing ctrl+up/down */
  82         int histlength; /* How long can the history be? */
  83
  84         GList *suggests;    /* List of suggestions */
  85         gboolean word;      /* Are the suggestions for only a word, or for the whole thing? */
  86         gboolean always;    /* Should the list of suggestions show at all times, or only on tab-press? */
  87         GntWidget *ddown;   /* The dropdown with the suggested list */
  88         GntEntryKillRing *killring; /**< @since 2.3.0 */
  89 };
  90
  91 struct _GntEntryClass
  92 {
  93         GntWidgetClass parent;
  94
  95         void (*text_changed)(GntEntry *entry);
  96         void (*gnt_reserved1)(void);
  97         void (*gnt_reserved2)(void);
  98         void (*gnt_reserved3)(void);
  99         void (*gnt_reserved4)(void);
 100 };
 101
 102 G_BEGIN_DECLS
 103
 104 /**
 105  * @return GType for GntEntry.
 106  */
 107 GType gnt_entry_get_gtype(void);
 108
 109 /**
 110  * Create a new GntEntry.
 111  *
 112  * @param text   The text in the new entry box.
 113  *
 114  * @return  The newly created entry box.
 115  */
 116 GntWidget * gnt_entry_new(const char *text);
 117
 118 /**
 119  * Set the maximum length of the text in the entry box.
 120  *
 121  * @param entry  The entry box.
 122  * @param max    The maximum length for text. A value of 0 means infinite length.
 123  */
 124 void gnt_entry_set_max(GntEntry *entry, int max);
 125
 126 /**
 127  * Set the text in an entry box.
 128  *
 129  * @param entry The entry box.
 130  * @param text  The text to set in the box.
 131  */
 132 void gnt_entry_set_text(GntEntry *entry, const char *text);
 133
 134 /**
 135  * Set flags an entry box.
 136  *
 137  * @param entry  The entry box.
 138  * @param flag   The flags to set for the entry box.
 139  */
 140 void gnt_entry_set_flag(GntEntry *entry, GntEntryFlag flag);
 141
 142 /**
 143  * Get the text in an entry box.
 144  *
 145  * @param entry  The entry box.
 146  *
 147  * @return   The current text in the entry box.
 148  */
 149 const char *gnt_entry_get_text(GntEntry *entry);
 150
 151 /**
 152  * Clear the text in the entry box.
 153  *
 154  * @param entry  The entry box.
 155  */
 156 void gnt_entry_clear(GntEntry *entry);
 157
 158 /**
 159  * Set whether the text in the entry box should be masked for display.
 160  *
 161  * @param entry  The entry box.
 162  * @param set    @c TRUE if the text should be masked, @c FALSE otherwise.
 163  */
 164 void gnt_entry_set_masked(GntEntry *entry, gboolean set);
 165
 166 /**
 167  * Add a text to the history list for the text. The history length for the
 168  * entry box needs to be set first by gnt_entry_set_history_length.
 169  *
 170  * @param entry  The entry box.
 171  * @param text   A new entry for the history list.
 172  */
 173 void gnt_entry_add_to_history(GntEntry *entry, const char *text);
 174
 175 /**
 176  * Set the length of history for the entry box.
 177  *
 178  * @param entry  The entry box.
 179  * @param num    The maximum length of the history.
 180  */
 181 void gnt_entry_set_history_length(GntEntry *entry, int num);
 182
 183 /**
 184  * Set whether the suggestions are for the entire entry box, or for each
 185  * individual word in the entry box.
 186  *
 187  * @param entry   The entry box.
 188  * @param word    @c TRUE if the suggestions are for individual words, @c FALSE otherwise.
 189  */
 190 void gnt_entry_set_word_suggest(GntEntry *entry, gboolean word);
 191
 192 /**
 193  * Set whether to always display the suggestions list, or only when the
 194  * tab-completion key is pressed (the TAB key, by default).
 195  *
 196  * @param entry    The entry box.
 197  * @param always   @c TRUE if the suggestion list should always be displayed.
 198  */
 199 void gnt_entry_set_always_suggest(GntEntry *entry, gboolean always);
 200
 201 /**
 202  * Add an item to the suggestion list.
 203  *
 204  * @param entry  The entry box.
 205  * @param text   An item to add to the suggestion list.
 206  */
 207 void gnt_entry_add_suggest(GntEntry *entry, const char *text);
 208
 209 /**
 210  * Remove an entry from the suggestion list.
 211  *
 212  * @param entry  The entry box.
 213  * @param text   The item to remove from the suggestion list.
 214  */
 215 void gnt_entry_remove_suggest(GntEntry *entry, const char *text);
 216
 217 G_END_DECLS
 218
 219 #endif /* GNT_ENTRY_H */