Source

wxPython / wx / lib / masked / numctrl.py

   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
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
#----------------------------------------------------------------------------
# Name:         wxPython.lib.masked.numctrl.py
# Author:       Will Sadkin
# Created:      09/06/2003
# Copyright:   (c) 2003-2007 by Will Sadkin
# RCS-ID:      $Id: numctrl.py 69476 2011-10-19 20:34:18Z RD $
# License:     wxWidgets license
#----------------------------------------------------------------------------
# NOTE:
#   This was written to provide a numeric edit control for wxPython that
#   does things like right-insert (like a calculator), and does grouping, etc.
#   (ie. the features of masked.TextCtrl), but allows Get/Set of numeric
#   values, rather than text.
#
#   Masked.NumCtrl permits integer, and floating point values to be set
#   retrieved or set via .GetValue() and .SetValue() (type chosen based on
#   fraction width, and provides an masked.EVT_NUM() event function for trapping
#   changes to the control.
#
#   It supports negative numbers as well as the naturals, and has the option
#   of not permitting leading zeros or an empty control; if an empty value is
#   not allowed, attempting to delete the contents of the control will result
#   in a (selected) value of zero, thus preserving a legitimate numeric value.
#   Similarly, replacing the contents of the control with '-' will result in
#   a selected (absolute) value of -1.
#
#   masked.NumCtrl also supports range limits, with the option of either
#   enforcing them or simply coloring the text of the control if the limits
#   are exceeded.
#
#   masked.NumCtrl is intended to support fixed-point numeric entry, and
#   is derived from BaseMaskedTextCtrl.  As such, it supports a limited range
#   of values to comply with a fixed-width entry mask.
#----------------------------------------------------------------------------
# 12/09/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o Updated for wx namespace
#
# 12/20/2003 - Jeff Grimmett (grimmtooth@softhome.net)
#
# o wxMaskedEditMixin -> MaskedEditMixin
# o wxMaskedTextCtrl -> masked.TextCtrl
# o wxMaskedNumNumberUpdatedEvent -> masked.NumberUpdatedEvent
# o wxMaskedNumCtrl -> masked.NumCtrl
#

"""
masked.NumCtrl:
  - allows you to get and set integer or floating point numbers as value,</LI>
  - provides bounds support and optional value limiting,</LI>
  - has the right-insert input style that MaskedTextCtrl supports,</LI>
  - provides optional automatic grouping, sign control and format, grouping and decimal
    character selection, etc. etc.</LI>


  Being derived from masked.TextCtrl, the control only allows
  fixed-point  notation.  That is, it has a fixed (though reconfigurable)
  maximum width for the integer portion and optional fixed width
  fractional portion.

  Here's the API::

        from wx.lib.masked import NumCtrl

        NumCtrl(
             parent, id = -1,
             value = 0,
             pos = wx.DefaultPosition,
             size = wx.DefaultSize,
             style = 0,
             validator = wx.DefaultValidator,
             name = "masked.number",
             integerWidth = 10,
             fractionWidth = 0,
             allowNone = False,
             allowNegative = True,
             useParensForNegatives = False,
             groupDigits = False,
             groupChar = ',',
             decimalChar = '.',
             min = None,
             max = None,
             limited = False,
             limitOnFieldChange = False,
             selectOnEntry = True,
             foregroundColour = "Black",
             signedForegroundColour = "Red",
             emptyBackgroundColour = "White",
             validBackgroundColour = "White",
             invalidBackgroundColour = "Yellow",
             autoSize = True
             )


  value
        If no initial value is set, the default will be zero, or
        the minimum value, if specified.  If an illegal string is specified,
        a ValueError will result. (You can always later set the initial
        value with SetValue() after instantiation of the control.)

  integerWidth
        Indicates how many places to the right of any decimal point
        should be allowed in the control.  This will, perforce, limit
        the size of the values that can be entered. This number need
        not include space for grouping characters or the sign, if either
        of these options are enabled, as the resulting underlying
        mask is automatically by the control.  The default of 10
        will allow any 32 bit integer value.  The minimum value
        for integerWidth is 1.

  fractionWidth
        Indicates how many decimal places to show for numeric value.
        If default (0), then the control will display and return only
        integer or long values.

  allowNone
        Boolean indicating whether or not the control is allowed to be
        empty, representing a value of None for the control.
        
  allowNegative
        Boolean indicating whether or not control is allowed to hold
        negative numbers.

  useParensForNegatives
        If true, this will cause negative numbers to be displayed with ()s
        rather than -, (although '-' will still trigger a negative number.)

  groupDigits
        Indicates whether or not grouping characters should be allowed and/or
        inserted when leaving the control or the decimal character is entered.

  groupChar
        What grouping character will be used if allowed. (By default ',')

  decimalChar
        If fractionWidth is > 0, what character will be used to represent
        the decimal point.  (By default '.')

  min
        The minimum value that the control should allow.  This can be also be
        adjusted with SetMin().  If the control is not limited, any value
        below this bound will result in a background colored with the current
        invalidBackgroundColour.  If the min specified will not fit into the
        control, the min setting will be ignored.

  max
        The maximum value that the control should allow.  This can be
        adjusted with SetMax().  If the control is not limited, any value
        above this bound will result in a background colored with the current
        invalidBackgroundColour.  If the max specified will not fit into the
        control, the max setting will be ignored.

  limited
        Boolean indicating whether the control prevents values from
        exceeding the currently set minimum and maximum values (bounds).
        If False and bounds are set, out-of-bounds values will
        result in a background colored with the current invalidBackgroundColour.

  limitOnFieldChange
        An alternative to limited, this boolean indicates whether or not a
        field change should be allowed if the value in the control
        is out of bounds.  If True, and control focus is lost, this will also
        cause the control to take on the nearest bound value.

  selectOnEntry
        Boolean indicating whether or not the value in each field of the
        control should be automatically selected (for replacement) when
        that field is entered, either by cursor movement or tabbing.
        This can be desirable when using these controls for rapid data entry.

  foregroundColour
        Color value used for positive values of the control.

  signedForegroundColour
        Color value used for negative values of the control.

  emptyBackgroundColour
        What background color to use when the control is considered
        "empty." (allow_none must be set to trigger this behavior.)

  validBackgroundColour
        What background color to use when the control value is
        considered valid.

  invalidBackgroundColour
        Color value used for illegal values or values out-of-bounds of the
        control when the bounds are set but the control is not limited.

  autoSize
        Boolean indicating whether or not the control should set its own
        width based on the integer and fraction widths.  True by default.
        <I>Note:</I> Setting this to False will produce seemingly odd
        behavior unless the control is large enough to hold the maximum
        specified value given the widths and the sign positions; if not,
        the control will appear to "jump around" as the contents scroll.
        (ie. autoSize is highly recommended.)

--------------------------

masked.EVT_NUM(win, id, func)
    Respond to a EVT_COMMAND_MASKED_NUMBER_UPDATED event, generated when
    the value changes. Notice that this event will always be sent when the
    control's contents changes - whether this is due to user input or
    comes from the program itself (for example, if SetValue() is called.)


SetValue(int|long|float|string)
    Sets the value of the control to the value specified, if
    possible.  The resulting actual value of the control may be
    altered to conform to the format of the control, changed
    to conform with the bounds set on the control if limited,
    or colored if not limited but the value is out-of-bounds.
    A ValueError exception will be raised if an invalid value
    is specified.

GetValue()
    Retrieves the numeric value from the control.  The value
    retrieved will be either be returned as a long if the
    fractionWidth is 0, or a float otherwise.


SetParameters(\*\*kwargs)
    Allows simultaneous setting of various attributes
    of the control after construction.  Keyword arguments
    allowed are the same parameters as supported in the constructor.


SetIntegerWidth(value)
    Resets the width of the integer portion of the control.  The
    value must be >= 1, or an AttributeError exception will result.
    This value should account for any grouping characters that might
    be inserted (if grouping is enabled), but does not need to account
    for the sign, as that is handled separately by the control.
GetIntegerWidth()
    Returns the current width of the integer portion of the control,
    not including any reserved sign position.


SetFractionWidth(value)
    Resets the width of the fractional portion of the control.  The
    value must be >= 0, or an AttributeError exception will result.  If
    0, the current value of the control will be truncated to an integer
    value.
GetFractionWidth()
    Returns the current width of the fractional portion of the control.


SetMin(min=None)
    Resets the minimum value of the control.  If a value of <I>None</I>
    is provided, then the control will have no explicit minimum value.
    If the value specified is greater than the current maximum value,
    then the function returns False and the minimum will not change from
    its current setting.  On success, the function returns True.

    If successful and the current value is lower than the new lower
    bound, if the control is limited, the value will be automatically
    adjusted to the new minimum value; if not limited, the value in the
    control will be colored as invalid.

    If min > the max value allowed by the width of the control,
    the function will return False, and the min will not be set.

GetMin()
    Gets the current lower bound value for the control.
    It will return None if no lower bound is currently specified.


SetMax(max=None)
    Resets the maximum value of the control. If a value of <I>None</I>
    is provided, then the control will have no explicit maximum value.
    If the value specified is less than the current minimum value, then
    the function returns False and the maximum will not change from its
    current setting. On success, the function returns True.

    If successful and the current value is greater than the new upper
    bound, if the control is limited the value will be automatically
    adjusted to this maximum value; if not limited, the value in the
    control will be colored as invalid.

    If max > the max value allowed by the width of the control,
    the function will return False, and the max will not be set.

GetMax()
    Gets the current upper bound value for the control.
    It will return None if no upper bound is currently specified.


SetBounds(min=None,max=None)
    This function is a convenience function for setting the min and max
    values at the same time.  The function only applies the maximum bound
    if setting the minimum bound is successful, and returns True
    only if both operations succeed.  <B><I>Note:</I> leaving out an argument
    will remove the corresponding bound.
GetBounds()
    This function returns a two-tuple (min,max), indicating the
    current bounds of the control.  Each value can be None if
    that bound is not set.


IsInBounds(value=None)
    Returns <I>True</I> if no value is specified and the current value
    of the control falls within the current bounds.  This function can also
    be called with a value to see if that value would fall within the current
    bounds of the given control.


SetLimited(bool)
    If called with a value of True, this function will cause the control
    to limit the value to fall within the bounds currently specified.
    If the control's value currently exceeds the bounds, it will then
    be limited accordingly.
    If called with a value of False, this function will disable value
    limiting, but coloring of out-of-bounds values will still take
    place if bounds have been set for the control.

GetLimited()

IsLimited()
    Returns <I>True</I> if the control is currently limiting the
    value to fall within the current bounds.

SetLimitOnFieldChange()
    If called with a value of True, will cause the control to allow
    out-of-bounds values, but will prevent field change if attempted
    via navigation, and if the control loses focus, it will change
    the value to the nearest bound.
    
GetLimitOnFieldChange()

IsLimitedOnFieldChange()
    Returns <I>True</I> if the control is currently limiting the
    value on field change.


SetAllowNone(bool)
    If called with a value of True, this function will cause the control
    to allow the value to be empty, representing a value of None.
    If called with a value of False, this function will prevent the value
    from being None.  If the value of the control is currently None,
    ie. the control is empty, then the value will be changed to that
    of the lower bound of the control, or 0 if no lower bound is set.

GetAllowNone()

IsNoneAllowed()
    Returns <I>True</I> if the control currently allows its
    value to be None.


SetAllowNegative(bool)
    If called with a value of True, this function will cause the
    control to allow the value to be negative (and reserve space for
    displaying the sign. If called with a value of False, and the
    value of the control is currently negative, the value of the
    control will be converted to the absolute value, and then
    limited appropriately based on the existing bounds of the control
    (if any).

GetAllowNegative()

IsNegativeAllowed()
    Returns <I>True</I> if the control currently permits values
    to be negative.


SetGroupDigits(bool)
    If called with a value of True, this will make the control
    automatically add and manage grouping characters to the presented
    value in integer portion of the control.

GetGroupDigits()

IsGroupingAllowed()
    Returns <I>True</I> if the control is currently set to group digits.


SetGroupChar()
    Sets the grouping character for the integer portion of the
    control.  (The default grouping character this is ','.
GetGroupChar()
    Returns the current grouping character for the control.


SetSelectOnEntry()
    If called with a value of <I>True</I>, this will make the control
    automatically select the contents of each field as it is entered
    within the control.  (The default is True.)
    GetSelectOnEntry()
    Returns <I>True</I> if the control currently auto selects
    the field values on entry.


SetAutoSize(bool)
    Resets the autoSize attribute of the control.
GetAutoSize()
    Returns the current state of the autoSize attribute for the control.

"""

import  copy
import  string
import  types

import  wx

from sys import maxint
MAXINT = maxint     # (constants should be in upper case)
MININT = -maxint-1

from wx.tools.dbg import Logger
from wx.lib.masked import MaskedEditMixin, Field, BaseMaskedTextCtrl
##dbg = Logger()
##dbg(enable=1)

#----------------------------------------------------------------------------

wxEVT_COMMAND_MASKED_NUMBER_UPDATED = wx.NewEventType()
EVT_NUM = wx.PyEventBinder(wxEVT_COMMAND_MASKED_NUMBER_UPDATED, 1)

#----------------------------------------------------------------------------

class NumberUpdatedEvent(wx.PyCommandEvent):
    """
    Used to fire an EVT_NUM event whenever the value in a NumCtrl changes.
    """

    def __init__(self, id, value = 0, object=None):
        wx.PyCommandEvent.__init__(self, wxEVT_COMMAND_MASKED_NUMBER_UPDATED, id)

        self.__value = value
        self.SetEventObject(object)

    def GetValue(self):
        """Retrieve the value of the control at the time
        this event was generated."""
        return self.__value


#----------------------------------------------------------------------------
class NumCtrlAccessorsMixin:
    """
    Defines masked.NumCtrl's list of attributes having their own
    Get/Set functions, ignoring those that make no sense for
    a numeric control.
    """
    exposed_basectrl_params = (
         'decimalChar',
         'shiftDecimalChar',
         'groupChar',
         'useParensForNegatives',
         'defaultValue',
         'description',

         'useFixedWidthFont',
         'autoSize',
         'signedForegroundColour',
         'emptyBackgroundColour',
         'validBackgroundColour',
         'invalidBackgroundColour',

         'emptyInvalid',
         'validFunc',
         'validRequired',
         'stopFieldChangeIfInvalid',
        )
    for param in exposed_basectrl_params:
        propname = param[0].upper() + param[1:]
        exec('def Set%s(self, value): self.SetCtrlParameters(%s=value)' % (propname, param))
        exec('def Get%s(self): return self.GetCtrlParameter("%s")''' % (propname, param))

        if param.find('Colour') != -1:
            # add non-british spellings, for backward-compatibility
            propname.replace('Colour', 'Color')

            exec('def Set%s(self, value): self.SetCtrlParameters(%s=value)' % (propname, param))
            exec('def Get%s(self): return self.GetCtrlParameter("%s")''' % (propname, param))



#----------------------------------------------------------------------------

class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin):
    """
    Masked edit control supporting "native" numeric values, ie. .SetValue(3), for
    example, and supporting a variety of formatting options, including automatic
    rounding specifiable precision, grouping and decimal place characters, etc.
    """


    valid_ctrl_params = {
        'integerWidth': 10,                 # by default allow all 32-bit integers
        'fractionWidth': 0,                 # by default, use integers
        'decimalChar': '.',                 # by default, use '.' for decimal point
        'allowNegative': True,              # by default, allow negative numbers
        'useParensForNegatives': False,     # by default, use '-' to indicate negatives
        'groupDigits': True,                # by default, don't insert grouping
        'groupChar': ',',                   # by default, use ',' for grouping
        'min': None,                        # by default, no bounds set
        'max': None,
        'limited': False,                   # by default, no limiting even if bounds set
        'limitOnFieldChange': False,        # by default, don't limit if changing fields, even if bounds set
        'allowNone': False,                 # by default, don't allow empty value
        'selectOnEntry': True,              # by default, select the value of each field on entry
        'foregroundColour': "Black",
        'signedForegroundColour': "Red",
        'emptyBackgroundColour': "White",
        'validBackgroundColour': "White",
        'invalidBackgroundColour': "Yellow",
        'useFixedWidthFont': True,          # by default, use a fixed-width font
        'autoSize': True,                   # by default, set the width of the control based on the mask
        }


    def __init__ (
                self, parent, id=-1, value = 0,
                pos = wx.DefaultPosition, size = wx.DefaultSize,
                style = wx.TE_PROCESS_TAB, validator = wx.DefaultValidator,
                name = "masked.num",
                **kwargs ):

##        dbg('masked.NumCtrl::__init__', indent=1)

        # Set defaults for control:
##        dbg('setting defaults:')
        for key, param_value in NumCtrl.valid_ctrl_params.items():
            # This is done this way to make setattr behave consistently with
            # "private attribute" name mangling
            setattr(self, '_' + key, copy.copy(param_value))

        # Assign defaults for all attributes:
        init_args = copy.deepcopy(NumCtrl.valid_ctrl_params)
##        dbg('kwargs:', kwargs)
        for key, param_value in kwargs.items():
            key = key.replace('Color', 'Colour')
            if key not in NumCtrl.valid_ctrl_params.keys():
                raise AttributeError('invalid keyword argument "%s"' % key)
            else:
                init_args[key] = param_value
##        dbg('init_args:', indent=1)
        for key, param_value in init_args.items():
##            dbg('%s:' % key, param_value)
            pass
##        dbg(indent=0)

        # Process initial fields for the control, as part of construction:
        if type(init_args['integerWidth']) != types.IntType:
            raise AttributeError('invalid integerWidth (%s) specified; expected integer' % repr(init_args['integerWidth']))
        elif init_args['integerWidth'] < 1:
            raise AttributeError('invalid integerWidth (%s) specified; must be > 0' % repr(init_args['integerWidth']))

        fields = {}

        if init_args.has_key('fractionWidth'):
            if type(init_args['fractionWidth']) != types.IntType:
                raise AttributeError('invalid fractionWidth (%s) specified; expected integer' % repr(self._fractionWidth))
            elif init_args['fractionWidth'] < 0:
                raise AttributeError('invalid fractionWidth (%s) specified; must be >= 0' % repr(init_args['fractionWidth']))
            self._fractionWidth = init_args['fractionWidth']

        if self._fractionWidth:
            fracmask = '.' + '#{%d}' % self._fractionWidth
##            dbg('fracmask:', fracmask)
            fields[1] = Field(defaultValue='0'*self._fractionWidth)
        else:
            fracmask = ''

        self._integerWidth = init_args['integerWidth']
        if init_args['groupDigits']:
            self._groupSpace = (self._integerWidth - 1) / 3
        else:
            self._groupSpace = 0
        intmask = '#{%d}' % (self._integerWidth + self._groupSpace)
        if self._fractionWidth:
            emptyInvalid = False
        else:
            emptyInvalid = True
        fields[0] = Field(formatcodes='r<>', emptyInvalid=emptyInvalid)
##        dbg('intmask:', intmask)

        # don't bother to reprocess these arguments:
        del init_args['integerWidth']
        del init_args['fractionWidth']

        self._autoSize = init_args['autoSize']
        if self._autoSize:
            formatcodes = 'FR<'
        else:
            formatcodes = 'R<'


        mask = intmask+fracmask

        # initial value of state vars
        self._oldvalue = 0
        self._integerEnd = 0
        self._typedSign = False

        # Construct the base control:
        BaseMaskedTextCtrl.__init__(
                self, parent, id, '',
                pos, size, style, validator, name,
                mask = mask,
                formatcodes = formatcodes,
                fields = fields,
                validFunc=self.IsInBounds,
                setupEventHandling = False)

        self.Bind(wx.EVT_SET_FOCUS, self._OnFocus )        ## defeat automatic full selection
        self.Bind(wx.EVT_KILL_FOCUS, self._OnKillFocus )   ## run internal validator
        self.Bind(wx.EVT_LEFT_DCLICK, self._OnDoubleClick)  ## select field under cursor on dclick
        self.Bind(wx.EVT_RIGHT_UP, self._OnContextMenu )    ## bring up an appropriate context menu
        self.Bind(wx.EVT_KEY_DOWN, self._OnKeyDown )       ## capture control events not normally seen, eg ctrl-tab.
        self.Bind(wx.EVT_CHAR, self._OnChar )              ## handle each keypress
        self.Bind(wx.EVT_TEXT, self.OnTextChange )      ## color control appropriately & keep
                                                           ## track of previous value for undo

        # Establish any additional parameters, with appropriate error checking
        self.SetParameters(**init_args)

        # right alignment with prefixed blanks doesn't work with wxPython 2.9+
        if wx.Platform == "__WXMSW__":
            self.SetWindowStyleFlag(self.GetWindowStyleFlag() | wx.TE_RIGHT)

        # Set the value requested (if possible)
##        wxCallAfter(self.SetValue, value)
        self.SetValue(value)

        # Ensure proper coloring:
        self.Refresh()
##        dbg('finished NumCtrl::__init__', indent=0)


    def SetParameters(self, **kwargs):
        """
        This function is used to initialize and reconfigure the control.
        See TimeCtrl module overview for available parameters.
        """
##        dbg('NumCtrl::SetParameters', indent=1)
        maskededit_kwargs = {}
        reset_fraction_width = False


        if( (kwargs.has_key('integerWidth') and kwargs['integerWidth'] != self._integerWidth)
            or (kwargs.has_key('fractionWidth') and kwargs['fractionWidth'] != self._fractionWidth)
            or (kwargs.has_key('groupDigits') and kwargs['groupDigits'] != self._groupDigits)
            or (kwargs.has_key('autoSize') and kwargs['autoSize'] != self._autoSize) ):

            fields = {}

            if kwargs.has_key('fractionWidth'):
                if type(kwargs['fractionWidth']) != types.IntType:
                    raise AttributeError('invalid fractionWidth (%s) specified; expected integer' % repr(kwargs['fractionWidth']))
                elif kwargs['fractionWidth'] < 0:
                    raise AttributeError('invalid fractionWidth (%s) specified; must be >= 0' % repr(kwargs['fractionWidth']))
                else:
                    if self._fractionWidth != kwargs['fractionWidth']:
                        self._fractionWidth = kwargs['fractionWidth']

            if self._fractionWidth:
                fracmask = '.' + '#{%d}' % self._fractionWidth
                fields[1] = Field(defaultValue='0'*self._fractionWidth)
                emptyInvalid = False
            else:
                emptyInvalid = True
                fracmask = ''
##            dbg('fracmask:', fracmask)

            if kwargs.has_key('integerWidth'):
                if type(kwargs['integerWidth']) != types.IntType:
##                    dbg(indent=0)
                    raise AttributeError('invalid integerWidth (%s) specified; expected integer' % repr(kwargs['integerWidth']))
                elif kwargs['integerWidth'] < 0:
##                    dbg(indent=0)
                    raise AttributeError('invalid integerWidth (%s) specified; must be > 0' % repr(kwargs['integerWidth']))
                else:
                    self._integerWidth = kwargs['integerWidth']

            if kwargs.has_key('groupDigits'):
                self._groupDigits = kwargs['groupDigits']

            if self._groupDigits:
                self._groupSpace = (self._integerWidth - 1) / 3
            else:
                self._groupSpace = 0

            intmask = '#{%d}' % (self._integerWidth + self._groupSpace)
##            dbg('intmask:', intmask)
            fields[0] = Field(formatcodes='r<>', emptyInvalid=emptyInvalid)
            maskededit_kwargs['fields'] = fields

            # don't bother to reprocess these arguments:
            if kwargs.has_key('integerWidth'):
                del kwargs['integerWidth']
            if kwargs.has_key('fractionWidth'):
                del kwargs['fractionWidth']

            maskededit_kwargs['mask'] = intmask+fracmask

        if kwargs.has_key('groupChar') or kwargs.has_key('decimalChar'):
            old_groupchar = self._groupChar     # save so we can reformat properly
            old_decimalchar = self._decimalChar
##            dbg("old_groupchar: '%s'" % old_groupchar)
##            dbg("old_decimalchar: '%s'" % old_decimalchar)
            groupchar = old_groupchar
            decimalchar = old_decimalchar
            old_numvalue = self._GetNumValue(self._GetValue())

            if kwargs.has_key('groupChar'):
                maskededit_kwargs['groupChar'] = kwargs['groupChar']
                groupchar = kwargs['groupChar']
            if kwargs.has_key('decimalChar'):
                maskededit_kwargs['decimalChar'] = kwargs['decimalChar']
                decimalchar = kwargs['decimalChar']

            # Add sanity check to make sure these are distinct, and if not,
            # raise attribute error
            if groupchar == decimalchar:
                raise AttributeError('groupChar and decimalChar must be distinct')


        # for all other parameters, assign keyword args as appropriate:
        for key, param_value in kwargs.items():
            key = key.replace('Color', 'Colour')
            if key not in NumCtrl.valid_ctrl_params.keys():
                raise AttributeError('invalid keyword argument "%s"' % key)
            elif key not in MaskedEditMixin.valid_ctrl_params.keys():
                setattr(self, '_' + key, param_value)
            elif key in ('mask', 'autoformat'): # disallow explicit setting of mask
                raise AttributeError('invalid keyword argument "%s"' % key)
            else:
                maskededit_kwargs[key] = param_value
##        dbg('kwargs:', kwargs)

        # reprocess existing format codes to ensure proper resulting format:
        formatcodes = self.GetCtrlParameter('formatcodes')
        if kwargs.has_key('allowNegative'):
            if kwargs['allowNegative'] and '-' not in formatcodes:
                formatcodes += '-'
                maskededit_kwargs['formatcodes'] = formatcodes
            elif not kwargs['allowNegative'] and '-' in formatcodes:
                formatcodes = formatcodes.replace('-','')
                maskededit_kwargs['formatcodes'] = formatcodes

        if kwargs.has_key('groupDigits'):
            if kwargs['groupDigits'] and ',' not in formatcodes:
                formatcodes += ','
                maskededit_kwargs['formatcodes'] = formatcodes
            elif not kwargs['groupDigits'] and ',' in formatcodes:
                formatcodes = formatcodes.replace(',','')
                maskededit_kwargs['formatcodes'] = formatcodes

        if kwargs.has_key('selectOnEntry'):
            self._selectOnEntry = kwargs['selectOnEntry']
##            dbg("kwargs['selectOnEntry']?", kwargs['selectOnEntry'], "'S' in formatcodes?", 'S' in formatcodes)
            if kwargs['selectOnEntry'] and 'S' not in formatcodes:
                formatcodes += 'S'
                maskededit_kwargs['formatcodes'] = formatcodes
            elif not kwargs['selectOnEntry'] and 'S' in formatcodes:
                formatcodes = formatcodes.replace('S','')
                maskededit_kwargs['formatcodes'] = formatcodes

        if kwargs.has_key('autoSize'):
            self._autoSize = kwargs['autoSize']
            if kwargs['autoSize'] and 'F' not in formatcodes:
                formatcodes += 'F'
                maskededit_kwargs['formatcodes'] = formatcodes
            elif not kwargs['autoSize'] and 'F' in formatcodes:
                formatcodes = formatcodes.replace('F', '')
                maskededit_kwargs['formatcodes'] = formatcodes


        if 'r' in formatcodes and self._fractionWidth:
            # top-level mask should only be right insert if no fractional
            # part will be shown; ie. if reconfiguring control, remove
            # previous "global" setting.
            formatcodes = formatcodes.replace('r', '')
            maskededit_kwargs['formatcodes'] = formatcodes


        if kwargs.has_key('limited'):
            if kwargs['limited'] and not self._limited:
                maskededit_kwargs['validRequired'] = True
            elif not kwargs['limited'] and self._limited:
                maskededit_kwargs['validRequired'] = False
            self._limited = kwargs['limited']

        if kwargs.has_key('limitOnFieldChange'):
            if kwargs['limitOnFieldChange'] and not self._limitOnFieldChange:
                maskededit_kwargs['stopFieldChangeIfInvalid'] = True
            elif kwargs['limitOnFieldChange'] and self._limitOnFieldChange:
                maskededit_kwargs['stopFieldChangeIfInvalid'] = False

##        dbg('maskededit_kwargs:', maskededit_kwargs)
        if maskededit_kwargs.keys():
            self.SetCtrlParameters(**maskededit_kwargs)

        # Go ensure all the format codes necessary are present:
        orig_intformat = intformat = self.GetFieldParameter(0, 'formatcodes')
        if 'r' not in intformat:
            intformat += 'r'
        if '>' not in intformat:
            intformat += '>'
        if intformat != orig_intformat:
            if self._fractionWidth:
                self.SetFieldParameters(0, formatcodes=intformat)
            else:
                self.SetCtrlParameters(formatcodes=intformat)

        # Record end of integer and place cursor there unless selecting, or select entire field:
        integerStart, integerEnd = self._fields[0]._extent
        if not self._fields[0]._selectOnFieldEntry:
            self.SetInsertionPoint(0)
            self.SetInsertionPoint(integerEnd)
            self.SetSelection(integerEnd, integerEnd)
        else:
            self.SetInsertionPoint(0)   # include any sign
            self.SetSelection(0, integerEnd)


        # Set min and max as appropriate:
        if kwargs.has_key('min'):
            min = kwargs['min']
            if( self._max is None
                or min is None
                or (self._max is not None and self._max >= min) ):
##                dbg('examining min')
                if min is not None:
                    try:
                        textmin = self._toGUI(min, apply_limits = False)
                    except ValueError:
##                        dbg('min will not fit into control; ignoring', indent=0)
                        raise
##                dbg('accepted min')
                self._min = min
            else:
##                dbg('ignoring min')
                pass


        if kwargs.has_key('max'):
            max = kwargs['max']
            if( self._min is None
                or max is None
                or (self._min is not None and self._min <= max) ):
##                dbg('examining max')
                if max is not None:
                    try:
                        textmax = self._toGUI(max, apply_limits = False)
                    except ValueError:
##                        dbg('max will not fit into control; ignoring', indent=0)
                        raise
##                dbg('accepted max')
                self._max = max
            else:
##                dbg('ignoring max')
                pass

        if kwargs.has_key('allowNegative'):
            self._allowNegative = kwargs['allowNegative']

        # Ensure current value of control obeys any new restrictions imposed:
        text = self._GetValue()
##        dbg('text value: "%s"' % text)
        if kwargs.has_key('groupChar') and self._groupChar != old_groupchar and text.find(old_groupchar) != -1:
            text = old_numvalue
##            dbg('old_groupchar: "%s" newgroupchar: "%s"' % (old_groupchar, self._groupChar))
        if kwargs.has_key('decimalChar') and self._decimalChar != old_decimalchar and text.find(old_decimalchar) != -1:
            text = old_numvalue
        
        if text != self._GetValue():
            if self._decimalChar != '.':
                # ensure latest decimal char is in "numeric value" so it won't be removed
                # when going to the GUI:
                text = text.replace('.', self._decimalChar)
            newtext = self._toGUI(text)
##            dbg('calling wx.TextCtrl.ChangeValue(self, %s)' % newtext)
            wx.TextCtrl.ChangeValue(self, newtext)

        value = self.GetValue()

##        dbg('self._allowNegative?', self._allowNegative)
        if not self._allowNegative and self._isNeg:
            value = abs(value)
##            dbg('abs(value):', value)
            self._isNeg = False

        elif not self._allowNone and BaseMaskedTextCtrl.GetValue(self) == '':
            if self._min > 0:
                value = self._min
            else:
                value = 0

        sel_start, sel_to = self.GetSelection()
        if self.IsLimited() and self._min is not None and value < self._min:
##            dbg('Set to min value:', self._min)
            self._ChangeValue(self._toGUI(self._min))

        elif self.IsLimited() and self._max is not None and value > self._max:
##            dbg('Setting to max value:', self._max)
            self._ChangeValue(self._toGUI(self._max))
        else:
            # reformat current value as appropriate to possibly new conditions
##            dbg('Reformatting value:', value)
            sel_start, sel_to = self.GetSelection()
            self._ChangeValue(self._toGUI(value))
        self.Refresh() # recolor as appropriate
##        dbg('finished NumCtrl::SetParameters', indent=0)



    def _GetNumValue(self, value):
        """
        This function attempts to "clean up" a text value, providing a regularized
        convertable string, via atol() or atof(), for any well-formed numeric text value.
        """
        return value.replace(self._groupChar, '').replace(self._decimalChar, '.').replace('(', '-').replace(')','').strip()


    def GetFraction(self, candidate=None):
        """
        Returns the fractional portion of the value as a float.  If there is no
        fractional portion, the value returned will be 0.0.
        """
        if not self._fractionWidth:
            return 0.0
        else:
            fracstart, fracend = self._fields[1]._extent
            if candidate is None:
                value = self._toGUI(BaseMaskedTextCtrl.GetValue(self))
            else:
                value = self._toGUI(candidate)
            fracstring = value[fracstart:fracend].strip()
            if not value:
                return 0.0
            else:
                return string.atof(fracstring)

    def _OnChangeSign(self, event):
##        dbg('NumCtrl::_OnChangeSign', indent=1)
        self._typedSign = True
        MaskedEditMixin._OnChangeSign(self, event)
##        dbg(indent=0)


    def _disallowValue(self):
##        dbg('NumCtrl::_disallowValue')
        # limited and -1 is out of bounds
        if self._typedSign:
            self._isNeg = False
        if not wx.Validator_IsSilent():
            wx.Bell()
        sel_start, sel_to = self._GetSelection()
##        dbg('queuing reselection of (%d, %d)' % (sel_start, sel_to))
        wx.CallAfter(self.SetInsertionPoint, sel_start)      # preserve current selection/position
        wx.CallAfter(self.SetSelection, sel_start, sel_to)


    def _OnChangeField(self, event):
        """
        This routine enhances the base masked control _OnFieldChange().  It's job
        is to ensure limits are imposed if limitOnFieldChange is enabled.
        """
##        dbg('NumCtrl::_OnFieldChange', indent=1)
        if self._limitOnFieldChange and not (self._min <= self.GetValue() <= self._max):
            self._disallowValue()
##            dbg('oob - field change disallowed',indent=0)
            return False
        else:
##            dbg(indent=0)
            return MaskedEditMixin._OnChangeField(self, event)     # call the baseclass function


    def _LostFocus(self):
        """
        On loss of focus, if limitOnFieldChange is set, ensure value conforms to limits.
        """
##        dbg('NumCtrl::_LostFocus', indent=1)
        if self._limitOnFieldChange:
##            dbg("limiting on loss of focus")
            value = self.GetValue()
            if self._min is not None and value < self._min:
##                dbg('Set to min value:', self._min)
                self._SetValue(self._toGUI(self._min))

            elif self._max is not None and value > self._max:
##                dbg('Setting to max value:', self._max)
                self._SetValue(self._toGUI(self._max))
            # (else do nothing.)
        # (else do nothing.)
##        dbg(indent=0)
        return True


    def _SetValue(self, value):
        """
        This routine supersedes the base masked control _SetValue().  It is
        needed to ensure that the value of the control is always representable/convertable
        to a numeric return value (via GetValue().)  This routine also handles
        automatic adjustment and grouping of the value without explicit intervention
        by the user.
        """

##        dbg('NumCtrl::_SetValue("%s")' % value, indent=1)

        if( (self._fractionWidth and value.find(self._decimalChar) == -1) or
            (self._fractionWidth == 0 and value.find(self._decimalChar) != -1) ) :
            value = self._toGUI(value)

        numvalue = self._GetNumValue(value)
##        dbg('cleansed value: "%s"' % numvalue)
        replacement = None

        if numvalue == "":
            if self._allowNone:
##                dbg('calling base BaseMaskedTextCtrl._SetValue(self, "%s")' % value)
                BaseMaskedTextCtrl._SetValue(self, value)
                self.Refresh()
##                dbg(indent=0)
                return
            elif self._min > 0 and self.IsLimited():
                replacement = self._min
            else:
                replacement = 0
##            dbg('empty value; setting replacement:', replacement)

        if replacement is None:
            # Go get the integer portion about to be set and verify its validity
            intstart, intend = self._fields[0]._extent
##            dbg('intstart, intend:', intstart, intend)
##            dbg('raw integer:"%s"' % value[intstart:intend])
            int = self._GetNumValue(value[intstart:intend])
            numval = self._fromGUI(value)

##            dbg('integer: "%s"' % int)
            try:
                # if a float value, this will implicitly verify against limits,
                # and generate an exception if out-of-bounds and limited
                # if not a float, it will just return 0.0, and we therefore
                # have to test against the limits explicitly after testing
                # special cases for handling -0 and empty controls...
                fracval = self.GetFraction(value)
            except ValueError, e:
##                dbg('Exception:', e, 'must be out of bounds; disallow value')
                self._disallowValue()
##                dbg(indent=0)
                return

            if fracval == 0.0: # (can be 0 for floats as well as integers)
                # we have to do special testing to account for emptying controls, or -0
                # and/or just leaving the sign character or changing the sign,
                # so we can do appropriate things to the value of the control,
                # we can't just immediately test to see if the value is valid
                # If all of these special cases are not in play, THEN we can do 
                # a limits check and see if the value is otherwise ok...

##                dbg('self._isNeg?', self._isNeg)
                if int == '-' and self._oldvalue < 0 and not self._typedSign:
##                    dbg('just a negative sign; old value < 0; setting replacement of 0')
                    replacement = 0
                    self._isNeg = False
                elif int[:2] == '-0': 
                    if self._oldvalue < 0:
##                        dbg('-0; setting replacement of 0')
                        replacement = 0
                        self._isNeg = False
                    elif not self._limited or (self._min < -1 and self._max >= -1):
##                        dbg('-0; setting replacement of -1')
                        replacement = -1
                        self._isNeg = True
                    else:
                        # limited and -1 is out of bounds
                        self._disallowValue()
##                        dbg(indent=0)
                        return

                elif int == '-' and (self._oldvalue >= 0 or self._typedSign):
                    if not self._limited or (self._min < -1 and self._max >= -1):
##                        dbg('just a negative sign; setting replacement of -1')
                        replacement = -1
                    else:
                        # limited and -1 is out of bounds
                        self._disallowValue()
##                        dbg(indent=0)
                        return

                elif( self._typedSign
                      and int.find('-') != -1
                      and self._limited
                      and not self._min <= numval <= self._max):
                    # changed sign resulting in value that's now out-of-bounds;
                    # disallow
                    self._disallowValue()
##                    dbg(indent=0)
                    return

            if replacement is None:
                if int and int != '-':
                    try:
                        string.atol(int)
                    except ValueError:
                        # integer requested is not legal.  This can happen if the user
                        # is attempting to insert a digit in the middle of the control
                        # resulting in something like "   3   45". Disallow such actions:
##                        dbg('>>>>>>>>>>>>>>>> "%s" does not convert to a long!' % int)
                        if not wx.Validator_IsSilent():
                            wx.Bell()
                        sel_start, sel_to = self._GetSelection()
##                        dbg('queuing reselection of (%d, %d)' % (sel_start, sel_to))
                        wx.CallAfter(self.SetInsertionPoint, sel_start)      # preserve current selection/position
                        wx.CallAfter(self.SetSelection, sel_start, sel_to)
##                        dbg(indent=0)
                        return

##                    dbg('numvalue: "%s"' % numvalue.replace(' ', ''))
                    # finally, (potentially re) verify that numvalue will pass any limits imposed:
                    try:
                        if self._fractionWidth:
                            value = self._toGUI(string.atof(numvalue))
                        else:
                            value = self._toGUI(string.atol(numvalue))
                    except ValueError, e:
##                        dbg('Exception:', e, 'must be out of bounds; disallow value')
                        self._disallowValue()
##                        dbg(indent=0)
                        return

##                        dbg('modified value: "%s"' % value)


        self._typedSign = False     # reset state var

        if replacement is not None:
            # Value presented wasn't a legal number, but control should do something
            # reasonable instead:
##            dbg('setting replacement value:', replacement)
            self._SetValue(self._toGUI(replacement))
            sel_start = BaseMaskedTextCtrl.GetValue(self).find(str(abs(replacement)))   # find where it put the 1, so we can select it
            sel_to = sel_start + len(str(abs(replacement)))
##            dbg('queuing selection of (%d, %d)' %(sel_start, sel_to))
            wx.CallAfter(self.SetInsertionPoint, sel_start)
            wx.CallAfter(self.SetSelection, sel_start, sel_to)
##            dbg(indent=0)
            return

        # Otherwise, apply appropriate formatting to value:

        # Because we're intercepting the value and adjusting it
        # before a sign change is detected, we need to do this here:
        if '-' in value or '(' in value:
            self._isNeg = True
        else:
            self._isNeg = False

##        dbg('value:"%s"' % value, 'self._useParens:', self._useParens)
        if self._fractionWidth:
            adjvalue = self._adjustFloat(self._GetNumValue(value).replace('.',self._decimalChar))
        else:
            adjvalue = self._adjustInt(self._GetNumValue(value))
##        dbg('adjusted value: "%s"' % adjvalue)


        sel_start, sel_to = self._GetSelection()     # record current insertion point
##        dbg('calling BaseMaskedTextCtrl._SetValue(self, "%s")' % adjvalue)
        BaseMaskedTextCtrl._SetValue(self, adjvalue)
        # After all actions so far scheduled, check that resulting cursor
        # position is appropriate, and move if not:
        wx.CallAfter(self._CheckInsertionPoint)

##        dbg('finished NumCtrl::_SetValue', indent=0)

    def _CheckInsertionPoint(self):
        # If current insertion point is before the end of the integer and
        # its before the 1st digit, place it just after the sign position:
##        dbg('NumCtrl::CheckInsertionPoint', indent=1)
        sel_start, sel_to = self._GetSelection()
        text = self._GetValue()
        if sel_to < self._fields[0]._extent[1] and text[sel_to] in (' ', '-', '('):
            text, signpos, right_signpos = self._getSignedValue()
##            dbg('setting selection(%d, %d)' % (signpos+1, signpos+1))
            self.SetInsertionPoint(signpos+1)
            self.SetSelection(signpos+1, signpos+1)
##        dbg(indent=0)


    def _OnErase( self, event=None, just_return_value=False ):
        """
        This overrides the base control _OnErase, so that erasing around
        grouping characters auto selects the digit before or after the
        grouping character, so that the erasure does the right thing.
        """
##        dbg('NumCtrl::_OnErase', indent=1)
        if event is None:   # called as action routine from Cut() operation.
            key = wx.WXK_DELETE
        else:
            key = event.GetKeyCode()
        #if grouping digits, make sure deletes next to group char always
        # delete next digit to appropriate side:
        if self._groupDigits:
            value = BaseMaskedTextCtrl.GetValue(self)
            sel_start, sel_to = self._GetSelection()

            if key == wx.WXK_BACK:
                # if 1st selected char is group char, select to previous digit
                if sel_start > 0 and sel_start < len(self._mask) and value[sel_start:sel_to] == self._groupChar:
                    self.SetInsertionPoint(sel_start-1)
                    self.SetSelection(sel_start-1, sel_to)

                # elif previous char is group char, select to previous digit
                elif sel_start > 1 and sel_start == sel_to and value[sel_start-1:sel_start] == self._groupChar:
                    self.SetInsertionPoint(sel_start-2)
                    self.SetSelection(sel_start-2, sel_to)

            elif key == wx.WXK_DELETE:
                if( sel_to < len(self._mask) - 2 + (1 *self._useParens)
                    and sel_start == sel_to
                    and value[sel_to] == self._groupChar ):
                    self.SetInsertionPoint(sel_start)
                    self.SetSelection(sel_start, sel_to+2)

                elif( sel_to < len(self._mask) - 2 + (1 *self._useParens)
                           and value[sel_start:sel_to] == self._groupChar ):
                    self.SetInsertionPoint(sel_start)
                    self.SetSelection(sel_start, sel_to+1)
##        dbg(indent=0)
        return BaseMaskedTextCtrl._OnErase(self, event, just_return_value)


    def OnTextChange( self, event ):
        """
        Handles an event indicating that the text control's value
        has changed, and issue EVT_NUM event.
        NOTE: using wxTextCtrl.SetValue() to change the control's
        contents from within a EVT_CHAR handler can cause double
        text events.  So we check for actual changes to the text
        before passing the events on.
        """
##        dbg('NumCtrl::OnTextChange', indent=1)
        if not BaseMaskedTextCtrl._OnTextChange(self, event):
##            dbg(indent=0)
            return

        # else... legal value

        value = self.GetValue()
        if value != self._oldvalue:
            try:
                self.GetEventHandler().ProcessEvent(
                    NumberUpdatedEvent( self.GetId(), self.GetValue(), self ) )
            except ValueError:
##                dbg(indent=0)
                return
            # let normal processing of the text continue
            event.Skip()
        self._oldvalue = value # record for next event
##        dbg(indent=0)

    def _GetValue(self):
        """
        Override of BaseMaskedTextCtrl to allow mixin to get the raw text value of the
        control with this function.
        """
        return wx.TextCtrl.GetValue(self)


    def GetValue(self):
        """
        Returns the current numeric value of the control.
        """
        return self._fromGUI( BaseMaskedTextCtrl.GetValue(self) )

    def SetValue(self, value):
        """
        Sets the value of the control to the value specified.
        The resulting actual value of the control may be altered to
        conform with the bounds set on the control if limited,
        or colored if not limited but the value is out-of-bounds.
        A ValueError exception will be raised if an invalid value
        is specified.
        """
##        dbg('NumCtrl::SetValue(%s)' % value, indent=1)
        BaseMaskedTextCtrl.SetValue( self, self._toGUI(value) )
##        dbg(indent=0)

    def ChangeValue(self, value):
        """
        Sets the value of the control to the value specified.
        The resulting actual value of the control may be altered to
        conform with the bounds set on the control if limited,
        or colored if not limited but the value is out-of-bounds.
        A ValueError exception will be raised if an invalid value
        is specified.
        """
##        dbg('NumCtrl::ChangeValue(%s)' % value, indent=1)
        BaseMaskedTextCtrl.ChangeValue( self, self._toGUI(value) )
##        dbg(indent=0)




    def SetIntegerWidth(self, value):
        self.SetParameters(integerWidth=value)
    def GetIntegerWidth(self):
        return self._integerWidth

    def SetFractionWidth(self, value):
        self.SetParameters(fractionWidth=value)
    def GetFractionWidth(self):
        return self._fractionWidth



    def SetMin(self, min=None):
        """
        Sets the minimum value of the control.  If a value of None
        is provided, then the control will have no explicit minimum value.
        If the value specified is greater than the current maximum value,
        then the function returns False and the minimum will not change from
        its current setting.  On success, the function returns True.

        If successful and the current value is lower than the new lower
        bound, if the control is limited, the value will be automatically
        adjusted to the new minimum value; if not limited, the value in the
        control will be colored as invalid.

        If min > the max value allowed by the width of the control,
        the function will return False, and the min will not be set.
        """
##        dbg('NumCtrl::SetMin(%s)' % repr(min), indent=1)
        if( self._max is None
            or min is None
            or (self._max is not None and self._max >= min) ):
            try:
                self.SetParameters(min=min)
                bRet = True
            except ValueError:
                bRet = False
        else:
            bRet = False
##        dbg(indent=0)
        return bRet

    def GetMin(self):
        """
        Gets the lower bound value of the control.  It will return
        None if not specified.
        """
        return self._min


    def SetMax(self, max=None):
        """
        Sets the maximum value of the control. If a value of None
        is provided, then the control will have no explicit maximum value.
        If the value specified is less than the current minimum value, then
        the function returns False and the maximum will not change from its
        current setting. On success, the function returns True.

        If successful and the current value is greater than the new upper
        bound, if the control is limited the value will be automatically
        adjusted to this maximum value; if not limited, the value in the
        control will be colored as invalid.

        If max > the max value allowed by the width of the control,
        the function will return False, and the max will not be set.
        """
        if( self._min is None
            or max is None
            or (self._min is not None and self._min <= max) ):
            try:
                self.SetParameters(max=max)
                bRet = True
            except ValueError:
                bRet = False
        else:
            bRet = False

        return bRet


    def GetMax(self):
        """
        Gets the maximum value of the control.  It will return the current
        maximum integer, or None if not specified.
        """
        return self._max


    def SetBounds(self, min=None, max=None):
        """
        This function is a convenience function for setting the min and max
        values at the same time.  The function only applies the maximum bound
        if setting the minimum bound is successful, and returns True
        only if both operations succeed.
        NOTE: leaving out an argument will remove the corresponding bound.
        """
        ret = self.SetMin(min)
        return ret and self.SetMax(max)


    def GetBounds(self):
        """
        This function returns a two-tuple (min,max), indicating the
        current bounds of the control.  Each value can be None if
        that bound is not set.
        """
        return (self._min, self._max)


    def SetLimited(self, limited):
        """
        If called with a value of True, this function will cause the control
        to limit the value to fall within the bounds currently specified.
        If the control's value currently exceeds the bounds, it will then
        be limited accordingly.

        If called with a value of False, this function will disable value
        limiting, but coloring of out-of-bounds values will still take
        place if bounds have been set for the control.
        """
        self.SetParameters(limited = limited)


    def IsLimited(self):
        """
        Returns True if the control is currently limiting the
        value to fall within the current bounds.
        """
        return self._limited

    def GetLimited(self):
        """ (For regularization of property accessors) """
        return self.IsLimited()

    def SetLimitOnFieldChange(self, limit):
        """
        If called with a value of True, this function will cause the control
        to prevent navigation out of the current field if its value is out-of-bounds,
        and limit the value to fall within the bounds currently specified if the
        control loses focus.

        If called with a value of False, this function will disable value
        limiting, but coloring of out-of-bounds values will still take
        place if bounds have been set for the control.
        """
        self.SetParameters(limitOnFieldChange = limit)


    def IsLimitedOnFieldChange(self):
        """
        Returns True if the control is currently limiting the
        value to fall within the current bounds.
        """
        return self._limitOnFieldChange

    def GetLimitOnFieldChange(self):
        """ (For regularization of property accessors) """
        return self.IsLimitedOnFieldChange()


    def IsInBounds(self, value=None):
        """
        Returns True if no value is specified and the current value
        of the control falls within the current bounds.  This function can
        also be called with a value to see if that value would fall within
        the current bounds of the given control.
        """
##        dbg('IsInBounds(%s)' % repr(value), indent=1)
        if value is None:
            value = self.GetValue()
        else:
            try:
                value = self._GetNumValue(self._toGUI(value))
            except ValueError, e:
##                dbg('error getting NumValue(self._toGUI(value)):', e, indent=0)
                return False
            if value.strip() == '':
                value = None
            elif self._fractionWidth:
                value = float(value)
            else:
                value = long(value)

        min = self.GetMin()
        max = self.GetMax()
        if min is None: min = value
        if max is None: max = value

        # if bounds set, and value is None, return False
        if value == None and (min is not None or max is not None):
##            dbg('finished IsInBounds', indent=0)
            return 0
        else:
##            dbg('finished IsInBounds', indent=0)
            return min <= value <= max


    def SetAllowNone(self, allow_none):
        """
        Change the behavior of the validation code, allowing control
        to have a value of None or not, as appropriate.  If the value
        of the control is currently None, and allow_none is False, the
        value of the control will be set to the minimum value of the
        control, or 0 if no lower bound is set.
        """
        self._allowNone = allow_none
        if not allow_none and self.GetValue() is None:
            min = self.GetMin()
            if min is not None: self.SetValue(min)
            else:               self.SetValue(0)


    def IsNoneAllowed(self):
        return self._allowNone
    def GetAllowNone(self):
        """ (For regularization of property accessors) """
        return self.IsNoneAllowed()

    def SetAllowNegative(self, value):
        self.SetParameters(allowNegative=value)
    def IsNegativeAllowed(self):
        return self._allowNegative
    def GetAllowNegative(self):
        """ (For regularization of property accessors) """
        return self.IsNegativeAllowed()

    def SetGroupDigits(self, value):
        self.SetParameters(groupDigits=value)
    def IsGroupingAllowed(self):
        return self._groupDigits
    def GetGroupDigits(self):
        """ (For regularization of property accessors) """
        return self.IsGroupingAllowed()

    def SetGroupChar(self, value):
        self.SetParameters(groupChar=value)
    def GetGroupChar(self):
        return self._groupChar

    def SetDecimalChar(self, value):
        self.SetParameters(decimalChar=value)
    def GetDecimalChar(self):
        return self._decimalChar

    def SetSelectOnEntry(self, value):
        self.SetParameters(selectOnEntry=value)
    def GetSelectOnEntry(self):
        return self._selectOnEntry

    def SetAutoSize(self, value):
        self.SetParameters(autoSize=value)
    def GetAutoSize(self):
        return self._autoSize


    # (Other parameter accessors are inherited from base class)


    def _toGUI( self, value, apply_limits = True ):
        """
        Conversion function used to set the value of the control; does
        type and bounds checking and raises ValueError if argument is
        not a valid value.
        """
##        dbg('NumCtrl::_toGUI(%s)' % repr(value), indent=1)
        if value is None and self.IsNoneAllowed():
##            dbg(indent=0)
            return self._template

        elif type(value) in (types.StringType, types.UnicodeType):
            value = self._GetNumValue(value)
##            dbg('cleansed num value: "%s"' % value)
            if value == "":
                if self.IsNoneAllowed():
##                    dbg(indent=0)
                    return self._template
                else:
##                    dbg('exception raised:', e, indent=0)
                    raise ValueError ('NumCtrl requires numeric value, passed %s'% repr(value) )
            # else...
            try:
                if self._fractionWidth or value.find('.') != -1:
                    value = float(value)
                else:
                    value = long(value)
            except Exception, e:
##                dbg('exception raised:', e, indent=0)
                raise ValueError ('NumCtrl requires numeric value, passed %s'% repr(value) )

        elif type(value) not in (types.IntType, types.LongType, types.FloatType):
##            dbg(indent=0)
            raise ValueError (
                'NumCtrl requires numeric value, passed %s'% repr(value) )

        if not self._allowNegative and value < 0:
            raise ValueError (
                'control configured to disallow negative values, passed %s'% repr(value) )

        if self.IsLimited() and apply_limits:
            min = self.GetMin()
            max = self.GetMax()
            if not min is None and value < min:
##                dbg(indent=0)
                raise ValueError (
                    'value %d is below minimum value of control'% value )
            if not max is None and value > max:
##                dbg(indent=0)
                raise ValueError (
                    'value %d exceeds value of control'% value )

        adjustwidth = len(self._mask) - (1 * self._useParens * self._signOk)
##        dbg('len(%s):' % self._mask, len(self._mask))
##        dbg('adjustwidth - groupSpace:', adjustwidth - self._groupSpace)
##        dbg('adjustwidth:', adjustwidth)
        if self._fractionWidth == 0:
            s = str(long(value)).rjust(self._integerWidth)
        else:
            format = '%' + '%d.%df' % (self._integerWidth+self._fractionWidth+1, self._fractionWidth)
            s = format % float(value)
##        dbg('s:"%s"' % s, 'len(s):', len(s))
        if len(s) > (adjustwidth - self._groupSpace):
##            dbg(indent=0)
            raise ValueError ('value %s exceeds the integer width of the control (%d)' % (s, self._integerWidth))
        elif s[0] not in ('-', ' ') and self._allowNegative and len(s) == (adjustwidth - self._groupSpace):
##            dbg(indent=0)
            raise ValueError ('value %s exceeds the integer width of the control (%d)' % (s, self._integerWidth))

        s = s.rjust(adjustwidth).replace('.', self._decimalChar)
        if self._signOk and self._useParens:
            if s.find('-') != -1:
                s = s.replace('-', '(') + ')'
            else:
                s += ' '
##        dbg('returned: "%s"' % s, indent=0)
        return s


    def _fromGUI( self, value ):
        """
        Conversion function used in getting the value of the control.
        """
##        dbg(suspend=0)
##        dbg('NumCtrl::_fromGUI(%s)' % value, indent=1)
        # One or more of the underlying text control implementations
        # issue an intermediate EVT_TEXT when replacing the control's
        # value, where the intermediate value is an empty string.
        # So, to ensure consistency and to prevent spurious ValueErrors,
        # we make the following test, and react accordingly:
        #
        if value.strip() == '':
            if not self.IsNoneAllowed():
##                dbg('empty value; not allowed,returning 0', indent = 0)
                if self._fractionWidth:
                    return 0.0
                else:
                    return 0
            else:
##                dbg('empty value; returning None', indent = 0)
                return None
        else:
            value = self._GetNumValue(value)
##            dbg('Num value: "%s"' % value)
            if self._fractionWidth:
                try:
##                    dbg(indent=0)
                    return float( value )
                except ValueError:
##                    dbg("couldn't convert to float; returning None")
                    return None
                else:
                    raise
            else:
                try:
##                    dbg(indent=0)
                    return int( value )
                except ValueError:
                    try:
##                       dbg(indent=0)
                       return long( value )
                    except ValueError:
##                       dbg("couldn't convert to long; returning None")
                       return None

                    else:
                       raise
                else:
##                    dbg('exception occurred; returning None')
                    return None


    def _Paste( self, value=None, raise_on_invalid=False, just_return_value=False ):
        """
        Preprocessor for base control paste; if value needs to be right-justified
        to fit in control, do so prior to paste:
        """
##        dbg('NumCtrl::_Paste (value = "%s")' % value, indent=1)
        if value is None:
            paste_text = self._getClipboardContents()
        else:
            paste_text = value
        sel_start, sel_to = self._GetSelection()
        orig_sel_start = sel_start
        orig_sel_to = sel_to
##        dbg('selection:', (sel_start, sel_to))
        old_value = self._GetValue()

        #
        field = self._FindField(sel_start)
        edit_start, edit_end = field._extent

        # handle possibility of groupChar being a space:
        newtext = paste_text.lstrip()
        lspace_count = len(paste_text) - len(newtext)
        paste_text = ' ' * lspace_count  + newtext.replace(self._groupChar, '').replace('(', '-').replace(')','')

        if field._insertRight and self._groupDigits:
            # want to paste to the left; see if it will fit:
            left_text = old_value[edit_start:sel_start].lstrip()
##            dbg('len(left_text):', len(left_text))
##            dbg('len(paste_text):', len(paste_text))
##            dbg('sel_start - (len(left_text) + len(paste_text)) >= edit_start?', sel_start - (len(left_text) + len(paste_text)) >= edit_start)
            if sel_start - (len(left_text) + len(paste_text)) >= edit_start:
                # will fit! create effective paste text, and move cursor back to do so:
                paste_text = left_text + paste_text
                sel_start -= len(paste_text)
                sel_start += sel_to - orig_sel_start    # decrease by amount selected
            else:
##                dbg("won't fit left;", 'paste text remains: "%s"' % paste_text)
##                dbg('adjusted start before accounting for grouping:', sel_start)
##                dbg('adjusted paste_text before accounting for grouping: "%s"' % paste_text)
                pass
            if self._groupDigits and sel_start != orig_sel_start:
                left_len = len(old_value[:sel_to].lstrip())
                # remove group chars from adjusted paste string, and left pad to wipe out
                # old characters, so that selection will remove the right chars, and
                # readjust will do the right thing:
                paste_text = paste_text.replace(self._groupChar,'')
                adjcount = left_len - len(paste_text)
                paste_text = ' ' * adjcount + paste_text
                sel_start = sel_to - len(paste_text)
##                dbg('adjusted start after accounting for grouping:', sel_start)
##                dbg('adjusted paste_text after accounting for grouping: "%s"' % paste_text)
            self.SetInsertionPoint(sel_to)
            self.SetSelection(sel_start, sel_to)

        new_text, replace_to = MaskedEditMixin._Paste(self,
                                        paste_text,
                                        raise_on_invalid=raise_on_invalid,
                                        just_return_value=True)
        self._SetInsertionPoint(orig_sel_to)
        self._SetSelection(orig_sel_start, orig_sel_to)
        if not just_return_value and new_text is not None:
            if new_text != self._GetValue():
                    self.modified = True
            if new_text == '':
                self.ClearValue()
            else:
                wx.CallAfter(self._SetValue, new_text)
                wx.CallAfter(self._SetInsertionPoint, replace_to)
##            dbg(indent=0)
        else:
##            dbg(indent=0)
            return new_text, replace_to

    def _Undo(self, value=None, prev=None):
        '''numctrl's undo is more complicated than the base control's, due to
        grouping characters; we don't want to consider them when calculating
        the undone portion.'''
##        dbg('NumCtrl::_Undo', indent=1)
        if value is None: value = self._GetValue()
        if prev is None: prev = self._prevValue
        if not self._groupDigits:
            ignore, (new_sel_start, new_sel_to) = BaseMaskedTextCtrl._Undo(self, value, prev, just_return_results = True)
            self._SetValue(prev)
            self._SetInsertionPoint(new_sel_start)
            self._SetSelection(new_sel_start, new_sel_to)
            self._prevSelection = (new_sel_start, new_sel_to)
##            dbg('resetting "prev selection" to', self._prevSelection)
##            dbg(indent=0)
            return
        # else...
        sel_start, sel_to = self._prevSelection
        edit_start, edit_end = self._FindFieldExtent(0)

        adjvalue = self._GetNumValue(value).rjust(self._masklength)
        adjprev  = self._GetNumValue(prev ).rjust(self._masklength)

        # move selection to account for "ungrouped" value:
        left_text = value[sel_start:].lstrip()
        numleftgroups = len(left_text) - len(left_text.replace(self._groupChar, ''))
        adjsel_start = sel_start + numleftgroups
        right_text = value[sel_to:].lstrip()
        numrightgroups = len(right_text) - len(right_text.replace(self._groupChar, ''))
        adjsel_to = sel_to + numrightgroups
##        dbg('adjusting "previous" selection from', (sel_start, sel_to), 'to:', (adjsel_start, adjsel_to))
        self._prevSelection = (adjsel_start, adjsel_to)

        # determine appropriate selection for ungrouped undo
        ignore, (new_sel_start, new_sel_to) = BaseMaskedTextCtrl._Undo(self, adjvalue, adjprev, just_return_results = True)

        # adjust new selection based on grouping:
        left_len = edit_end - new_sel_start
        numleftgroups = left_len / 3
        new_sel_start -= numleftgroups
        if numleftgroups and left_len % 3 == 0:
            new_sel_start += 1

        if new_sel_start < self._masklength and prev[new_sel_start] == self._groupChar:
            new_sel_start += 1

        right_len = edit_end - new_sel_to
        numrightgroups = right_len / 3
        new_sel_to -= numrightgroups

        if new_sel_to and prev[new_sel_to-1] == self._groupChar:
            new_sel_to -= 1

        if new_sel_start > new_sel_to:
            new_sel_to = new_sel_start

        # for numbers, we don't care about leading whitespace; adjust selection if
        # it includes leading space.
        prev_stripped = prev.lstrip()
        prev_start = self._masklength - len(prev_stripped)
        if new_sel_start < prev_start:
            new_sel_start = prev_start

##        dbg('adjusted selection accounting for grouping:', (new_sel_start, new_sel_to))
        self._SetValue(prev)
        self._SetInsertionPoint(new_sel_start)
        self._SetSelection(new_sel_start, new_sel_to)
        self._prevSelection = (new_sel_start, new_sel_to)
##        dbg('resetting "prev selection" to', self._prevSelection)
##        dbg(indent=0)

#===========================================================================

if __name__ == '__main__':

    import traceback

    class myDialog(wx.Dialog):
        def __init__(self, parent, id, title,
            pos = wx.DefaultPosition, size = wx.DefaultSize,
            style = wx.DEFAULT_DIALOG_STYLE ):
            wx.Dialog.__init__(self, parent, id, title, pos, size, style)

            self.int_ctrl = NumCtrl(self, wx.NewId(), size=(55,20))
            self.OK = wx.Button( self, wx.ID_OK, "OK")
            self.Cancel = wx.Button( self, wx.ID_CANCEL, "Cancel")

            vs = wx.BoxSizer( wx.VERTICAL )
            vs.Add( self.int_ctrl, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
            hs = wx.BoxSizer( wx.HORIZONTAL )
            hs.Add( self.OK, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
            hs.Add( self.Cancel, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
            vs.Add(hs, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )

            self.SetAutoLayout( True )
            self.SetSizer( vs )
            vs.Fit( self )
            vs.SetSizeHints( self )
            self.Bind(EVT_NUM, self.OnChange, self.int_ctrl)

        def OnChange(self, event):
            print 'value now', event.GetValue()

    class TestApp(wx.App):
        def OnInit(self):
            try:
                self.frame = wx.Frame(None, -1, "Test", (20,20), (120,100)  )
                self.panel = wx.Panel(self.frame, -1)
                button = wx.Button(self.panel, -1, "Push Me", (20, 20))
                self.Bind(wx.EVT_BUTTON, self.OnClick, button)
            except:
                traceback.print_exc()
                return False
            return True

        def OnClick(self, event):
            dlg = myDialog(self.panel, -1, "test NumCtrl")
            dlg.int_ctrl.SetValue(501)
            dlg.int_ctrl.SetInsertionPoint(1)
            dlg.int_ctrl.SetSelection(1,2)
            rc = dlg.ShowModal()
            print 'final value', dlg.int_ctrl.GetValue()
            del dlg
            self.frame.Destroy()

        def Show(self):
            self.frame.Show(True)

    try:
        app = TestApp(0)
        app.Show()
        app.MainLoop()
    except:
        traceback.print_exc()

__i=0
## To-Do's:
## =============================##
##   1. Add support for printf-style format specification.
##   2. Add option for repositioning on 'illegal' insertion point.
##
## Version 1.4
##   1. In response to user request, added limitOnFieldChange feature, so that
##      out-of-bounds values can be temporarily added to the control, but should
##      navigation be attempted out of an invalid field, it will not navigate,
##      and if focus is lost on a control so limited with an invalid value, it
##      will change the value to the nearest bound.
##
## Version 1.3
##   1. fixed to allow space for a group char.
##
## Version 1.2
##   1. Allowed select/replace digits.
##   2. Fixed undo to ignore grouping chars.
##
## Version 1.1
##   1. Fixed .SetIntegerWidth() and .SetFractionWidth() functions.
##   2. Added autoSize parameter, to allow manual sizing of the control.
##   3. Changed inheritance to use wxBaseMaskedTextCtrl, to remove exposure of
##      nonsensical parameter methods from the control, so it will work
##      properly with Boa.
##   4. Fixed allowNone bug found by user sameerc1@grandecom.net
##