The package gtk+widgexts contains, at this moment, just the widget GtkxEntryMask.


This widget is based upon the GtkEntry widget and allows the programmer to set a type, thus preventing the input of invalid characters. It supports internationalization, so, for example, if the type is currency, it only allows locale numeric characters plus the positive and negative signs plus the decimal point and the thousands separator symbol.

To create a new GtkxEntryMask widget, call one of the following functions:

GtkWidget *gtkx_entrymask_new(void);
GtkWidget *gtkx_entrymask_new_with_type(GtkEntryMaskType type, const gchar *format, const gchar *mask);



The type can be one of the following:

  • ENTRYMASK_STRING The default value, is used to edit normal text.
  • ENTRYMASK_NUMERIC Used to edit numeric quantities
  • ENTRYMASK_CURRENCY Used to edit monetary quantities, showing the locale currency symbol
  • ENTRYMASK_DATE Used to edit dates
  • ENTRYMASK_TIME Used to edit times
  • ENTRYMASK_DATETIME Used to edit date-times or timespans



The mask depends on the type of the GtkEntryMask widget:

For string types, the mask can be formed by the following characters:

# Digit plus sign symbols and spaces.
9 Digit. No spaces allowed.
0 Digit. Spaces are replaced by 0.
A Alphabetic character
< Alphabetic character converted to upper case.
> Alphabetic character converted to lower case.

For numeric and currency types, the mask is formed by the following characters:

Digit. If the first character is zero, it is replaced with a blank
0 Digit. If the first character is zero, the zero is remained
. Decimal point position
, Thousands separator
+ The number doesn't admit the negative sign
* Repeat the mask pattern

For date and time types, the mask is formed by the following characters:

Day of the month
m Month
M Minutes

Here are some examples of masks and their meanings:

Note that if the mask is empty or NULL, the locale format for numbers, currencies, dates, times and datetimes is used.
STRING"+99 (\999)99-99-99"Telephone number. The +, the - and the parenthesis are fixed. The first 9 in the parenthesis is fixed
STRING"<<000"USA zip code
STRING""IP address
CURRENCYNULLLocale format for monetary quantities
CURRENCY"###,###.##"Quantity with two optional decimal digits and six optional integer digits, with thousands separator
CURRENCY"###,##0.00"Quantity with two fixed decimal digits and one integer fixed position and five optional integer digits, with thousands separator
NUMERICNULLLocale format for general quantities
NUMERIC"+00000"Quantity with five fixed integer digits, filled with zeroes to the left, without thousands separator. Only admits positive numbers
NUMERIC"*,###"Quantity with unlimited integer digits (about 20) with thousands separator and with no decimals
NUMERIC",*"Quantity with just decimal digits, up to about 8 digits
NUMERIC"##.0*"Quantity with two optional integer digits and up to about 8 fixed decimal digits
DATENULLLocale format for dates
DATE"mm/dd/yy"Date in mdy format, two digits for the year
DATE"dd/mm/yyyy"Date in dmy format, four digits for the year
TIMENULLLocale format for times
TIME"HH:MM"Hour and minutes
TIME"HH:MM:SS"Hour, minutes and seconds
DATETIMENULLLocale format for datetimes
DATETIME"dd/mm/yyyy HH:MM:SS"Datetime
DATETIME"mm/dd/yy HH:MM"Another form of datetime



The format property provides aditional information about the display of the text in the GtkEntryMask widget when it is not being edited.

STRING"<"The text is converted to uppercase
STRING">"The text is converted to lowercase
NUMERIC"$"The currency symbol is shown based on the locale settings
"B"If the quantity is zero, the entry is displayed blank
"%c", "%x %X", ...
(same as strftime)
The date is displayed in the format recognized by strftime



Example of use of the GtkxEntryMask widget. You can see the program textgtkentrymask that comes with the source bundle for more info.

#include <gtkwidgexts/gtkxentrymask.h>

/* Creation of the widget */
gtkwidget *txttelephone;
txttelephone = gtkx_entrymask_new_with_type (ENTRYMASK_STRING, NULL, "+99 (\\999)99-99-99");
gtk_widget_show (txttelephone);

gtkwidget *txtcost;
txtcost = gtkx_entrymask_new_with_type (ENTRYMASK_CURRENCY, NULL, "+000,000.00");
gtkx_entrymask_set_integer(txtcost, 123.45);
gtk_widget_show (txtcost);

/* ........... */

int cost = gtkx_entrymask_get_integer(txtcost);