This file is indexed.

/usr/share/mypaint/gui/document.py is in mypaint 1.2.0-4.1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   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
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
# -*- coding: utf-8 -*-
#
# This file is part of MyPaint.
# Copyright (C) 2007-2010 by Martin Renold <martinxyz@gmx.ch>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.

"""Top-level document controller classes

The classes defined here oparate as controllers in the MVC sense,
i.e. they convert user input into updates to the document model.
"""


## Imports

import os
import os.path
import math
from warnings import warn
import weakref
import logging
logger = logging.getLogger(__name__)

import gtk2compat
import gobject
import gtk
from gtk import gdk
from gtk import keysyms
from gettext import gettext as _
from gi.repository import Gio

import lib.layer
import lib.helpers
from lib.helpers import clamp
from lib.observable import event
import stategroup
from brushmanager import ManagedBrush
import dialogs
import gui.mode
import gui.colorpicker   # purely for registration
import gui.symmetry   # registration only
import gui.freehand
import gui.inktool   # registration only
import gui.buttonmap
import gui.externalapp
import gui.device
import gui.backgroundwindow


## Class definitions


class CanvasController (object):
    """Minimal canvas controller using a stack of modes.

    Basic CanvasController objects can be set up to handle scroll events
    like zooming or rotation only, pointer events like drawing only, or
    both.

    The actual interpretation of each event is delegated to the top item
    on the controller's modes stack: see `gui.mode` for details.
    Simpler modes may assume the basic CanvasController interface, more
    complex ones may require the full Document interface.

    """

    # NOTE: If muliple, editable, views of a single model are required,
    # NOTE: then this interface will have to be revised.

    ## Initialization

    def __init__(self, tdw):
        """Initialize.

        :param tdw: The view widget to attach handlers onto.
        :type tdw: gui.tileddrawwidget.TiledDrawWidget

        """
        object.__init__(self)
        self.tdw = tdw     #: the TiledDrawWidget being controlled.
        self.modes = gui.mode.ModeStack(self)  #: stack of delegates
        self.modes.default_mode_class = gui.freehand.FreehandMode
        self.modes.default_mode_kwargs = {"abrupt_start": True}

    def init_pointer_events(self):
        """Establish TDW event listeners for pointer button presses & drags.
        """
        self.tdw.connect("button-press-event", self.button_press_cb)
        self.tdw.connect("motion-notify-event", self.motion_notify_cb)
        self.tdw.connect("button-release-event", self.button_release_cb)

    def init_scroll_events(self):
        """Establish TDW event listeners for scroll-wheel actions.
        """
        self.tdw.connect("scroll-event", self.scroll_cb)
        self.tdw.add_events(gdk.SCROLL_MASK)

    ## Low-level GTK event handlers: delegated to the current mode

    def button_press_cb(self, tdw, event):
        """Delegate a button-press-event to the current mode"""
        mode = self.modes.top
        result = mode.button_press_cb(tdw, event)
        self._update_last_event_info(tdw, event)
        return result

    def button_release_cb(self, tdw, event):
        """Delegate a button-release-event to the current mode"""
        mode = self.modes.top
        result = mode.button_release_cb(tdw, event)
        self._update_last_event_info(tdw, event)
        return result

    def motion_notify_cb(self, tdw, event):
        """Delegate a motion-notify-event to the current mode"""
        mode = self.modes.top
        result = mode.motion_notify_cb(tdw, event)
        self._update_last_event_info(tdw, event)
        return result

    def scroll_cb(self, tdw, event):
        """Delegate a scroll-event to the current mode"""
        mode = self.modes.top
        result = mode.scroll_cb(tdw, event)
        self._update_last_event_info(tdw, event)
        return result

    def key_press_cb(self, win, tdw, event):
        """Delegate a key-press-event to the current mode"""
        mode = self.modes.top
        return mode.key_press_cb(win, tdw, event)

    def key_release_cb(self, win, tdw, event):
        """Delegate a key-release-event to the current mode"""
        mode = self.modes.top
        return mode.key_release_cb(win, tdw, event)

    def _update_last_event_info(self, tdw, event):
        # Update the stored details of the last event delegated.
        tdw.__last_event_x = event.x
        tdw.__last_event_y = event.y
        tdw.__last_event_time = event.time

    def get_last_event_info(self, tdw):
        """Get details of the last event delegated to a mode in the stack.

        :rtype: tuple
        :returns: event details: ``(time, x, y)``

        """
        t, x, y = 0, None, None
        try:
            t = tdw.__last_event_time
            x = tdw.__last_event_x
            y = tdw.__last_event_y
        except AttributeError:
            pass
        return (t, x, y)

    ## High-level event observing interface

    @event
    def input_stroke_ended(self, event):
        """Event: input stroke just ended

        An input stroke is a single button-down, move, button-up action. This
        sort of stroke is not the same as a brush engine stroke (see
        ``lib.document``). It is possible that the visible stroke starts
        earlier and ends later, depending on how the operating system maps
        pressure to button up/down events.

        :param self: Passed on to registered observers
        :param event: The button release event which ended the input stroke

        Observer functions and methods are called with the originating Document
        Controler and the GTK event as arguments. This is a good place to
        listen for "just painted something" events in some cases; ``app.brush``
        will contain everything needed about the input stroke which is ending.
        """
        pass

    @event
    def input_stroke_started(self, event):
        """Event: input stroke just started

        Callbacks interested in the start of an input stroke should be attached
        here. See `input_stroke_ended()`.
        """
        pass


class Document (CanvasController):  # TODO: rename to "DocumentController"
    """Manipulation of a loaded document via the the GUI.

    A `gui.Document` is something like a Controller in the MVC sense: it
    translates GtkAction activations and keypresses for changing the
    view into View (`gui.tileddrawwidget`) manipulations. It is also
    responsible for directly manipulating the Model (`lib.document` and
    some of its internals) in response to actions and keypresses.

    Some per-application state can be manipulated through this object
    too: for example the drawing brush which is owned by the main
    application singleton.
    """

    ## Class constants

    # Layers have this attr set temporarily if they don't have a name yet
    _NONAME_LAYER_REFNUM_ATTR = "_document_noname_ref_number"

    #: Rotation step amount for single-shot commands.
    #: Allows easy and quick rotation to 45/90/180 degrees.
    ROTATION_STEP = 2*math.pi/16

    # Constants for rotating and zooming by increments
    ROTATE_ANTICLOCKWISE = 4  #: Rotation step direction: RotateLeft
    ROTATE_CLOCKWISE = 8  #: Rotation step direction: RotateRight
    ZOOM_INWARDS = 16  #: Zoom step direction: into the canvas
    ZOOM_OUTWARDS = 32  #: Zoom step direction: out of the canvas

    # Step zoom and rotations can happen at specified locations, or these.
    CENTER_ON_VIEWPORT = 1  #: Zoom or rotate at the canvas center
    CENTER_ON_POINTER = 2  #: Zoom/rotate at the last observed pointer pos

    # Constants for panning (movement) by increments
    PAN_STEP = 0.2  #: Stepwise panning amount: proportion of the canvas size
    PAN_LEFT = 1  #: Stepwise panning direction: left
    PAN_RIGHT = 2  #: Stepwise panning direction: right
    PAN_UP = 3  #: Stepwise panning direction: up
    PAN_DOWN = 4  #: Stepwise panning direction: down

    # Picking
    MIN_PICKING_OPACITY = 0.1
    PICKING_RADIUS = 5

    # Opacity changing
    OPACITY_STEP = 0.08

    # Registration
    _INSTANCE_REFS = []

    ## Registry of controller instances

    @classmethod
    def get_instances(cls):
        """Iterates across all Document instances

        :returns: All Document instances registered
        :rtype: iterable
        """
        for instance_ref in cls._INSTANCE_REFS:
            instance = instance_ref()
            if not instance:
                continue
            yield instance

    @classmethod
    def get_primary_instance(cls):
        """Return the main application working doc"""
        primary_instance = None
        for instance in cls.get_instances():
            primary_instance = instance
            break
        return primary_instance

    @classmethod
    def get_active_instance(cls):
        """Get the Document instance which has the active tdw."""
        from gui.tileddrawwidget import TiledDrawWidget
        active_tdw = TiledDrawWidget.get_active_tdw()
        for instance in cls.get_instances():
            if instance.tdw is active_tdw:
                return instance
        return None

    ## Construction

    def __init__(self, app, tdw, model):
        """Constructor for a document controller

        :param app: main application instance
        :type app: gui.application.Application
        :param tdw: primary canvas widget for this controller
        :type tdw: gui.tileddrawwidget.TiledDrawWidget
        :param model: model document to be controlled and reflected
        :type model: lib.document.Document

        Document controllers initialized here are registered
        automatically with the class. See get_instances().

        """
        self.app = app
        self.model = model
        CanvasController.__init__(self, tdw)

        # Current mode observation
        self.modes.changed += self._modestack_changed_cb

        self.model.frame_enabled_changed += self._frame_enabled_changed_cb
        layerstack = self.model.layer_stack
        layerstack.symmetry_state_changed += self._symmetry_state_changed_cb

        # Deferred until after the app starts (runs in the first idle-
        # processing phase) as a workaround for https://gna.org/bugs/?14372
        # ([Windows] crash when moving the pen during startup)
        gobject.idle_add(self.init_pointer_events)
        gobject.idle_add(self.init_scroll_events)

        self.zoomlevel_values = [1.0/16, 1.0/8, 2.0/11, 0.25, 1.0/3, 0.50, 2.0/3,  # micro
                                 1.0, 1.5, 2.0, 3.0, 4.0, 5.5, 8.0,        # normal
                                 11.0, 16.0, 23.0, 32.0, 45.0, 64.0]       # macro

        default_zoom = self.app.preferences['view.default_zoom']
        self.tdw.scale = default_zoom
        self.tdw.zoom_min = min(self.zoomlevel_values)
        self.tdw.zoom_max = max(self.zoomlevel_values)

        # Device-specific brushes: save at end of stroke
        self.input_stroke_ended += self._input_stroke_ended_cb

        self._init_stategroups()

        leader = self.get_primary_instance()
        if leader is not None:
            # This is a secondary controller (e.g. the scratchpad)
            # which plays follow-the-leader for some events.
            assert isinstance(leader, Document)
            self.action_group = leader.action_group  # hack, but needed by tdw
        else:
            # This doc owns the Actions which are (sometimes) passed on to
            # followers to perform. Its model is also the main 'document'
            # being worked on by the user.
            self._init_actions()
            self._init_context_actions()
            for action in self.action_group.list_actions():
                self.app.kbm.takeover_action(action)
            for action in self.modes_action_group.list_actions():
                self.app.kbm.takeover_action(action)
            self._init_extra_keys()

            toggle_action = self.app.builder.get_object('ContextRestoreColor')
            toggle_action.set_active(self.app.preferences['misc.context_restores_color'])

        #: Saved transformation to allow FitView to be toggled.
        self.saved_view = None

        #: Viewport change/manipulation observers.
        self.view_changed_observers = []
        self.view_changed_observers.append(self._view_changed_cb)
        self._view_changed_notification_srcid = None
        do_notify = lambda *a: self.notify_view_changed()
        self.tdw.connect_after("size-allocate", do_notify)

        # Brush settings observers
        self.app.brush.observers.append(self._brush_settings_changed_cb)

        # External file edit requests
        self._layer_edit_manager = gui.externalapp.LayerEditManager(self)

        # Registration
        cls = self.__class__
        cls._INSTANCE_REFS.append(weakref.ref(self))

    def _init_actions(self):
        """Internal: initializes action groups & state reflection"""
        # Actions are defined in resources.xml, just grab a ref to
        # the groups.
        builder = self.app.builder
        self.action_group = builder.get_object('DocumentActions')
        self.modes_action_group = builder.get_object("ModeStackActions")

        # Fine-grained observation of various model objects
        cmdstack = self.model.command_stack
        layerstack = self.model.layer_stack
        observed_events = {
            self._update_command_stack_actions: [
                cmdstack.stack_updated,
            ],
            self._update_merge_layer_down_action: [
                # Depends on this layer and the layer beneath it
                # being compatible.
                layerstack.layer_properties_changed,
                layerstack.current_path_updated,
                layerstack.layer_inserted,
                layerstack.layer_deleted,
            ],
            self._update_normalize_layer_action: [
                layerstack.current_path_updated,
                layerstack.layer_properties_changed,
            ],
            self._update_layer_bubble_actions: [
                # Depends on where this layer lies in the stack
                layerstack.current_path_updated,
                layerstack.layer_inserted,
                layerstack.layer_deleted,
            ],
            self._update_layer_select_actions: [
                # Depends on where this layer lies in the stack
                layerstack.current_path_updated,
                layerstack.layer_inserted,
                layerstack.layer_deleted,
            ],
            self._update_trim_layer_action: [
                layerstack.current_path_updated,
            ],
            self._update_show_background_toggle: [
                layerstack.background_visible_changed,
                layerstack.current_layer_solo_changed,
            ],
            self._update_layer_solo_toggle: [
                layerstack.current_layer_solo_changed,
            ],
            self._update_layer_flag_toggles: [
                # Visible and Locked
                layerstack.current_path_updated,
                layerstack.layer_properties_changed,
            ],
            self._update_current_layer_actions: [
                layerstack.current_path_updated,
            ],
            self._update_external_layer_edit_actions: [
                layerstack.current_path_updated,
            ],
        }
        for observer_method, events in observed_events.items():
            for event in events:
                event += observer_method
            observer_method()

    def _init_context_actions(self):
        """Internal: initializes several brush shortcut-key actions"""
        ag = self.action_group
        context_actions = []
        for x in range(10):
            rt = _("Load brush settings from shortcut slot %d") % x
            st = _("Store brush settings in shortcut slot %d") % x
            r = ('Context0%d' % x, None, _('Restore Brush %d') % x,
                 '%d' % x, rt, self.context_cb)
            s = ('Context0%ds' % x, None, _('Save to Brush %d') % x,
                 '<control>%d' % x, st, self.context_cb)
            context_actions.append(s)
            context_actions.append(r)
        ag.add_actions(context_actions)

    def _init_stategroups(self):
        """Internal: initializes internal StateGroups"""
        sg = stategroup.StateGroup()
        self.layerblink_state = sg.create_state(self.layerblink_state_enter,
                                                self.layerblink_state_leave)
        sg = stategroup.StateGroup()
        self.strokeblink_state = sg.create_state(self.strokeblink_state_enter,
                                                 self.strokeblink_state_leave)
        self.strokeblink_state.autoleave_timeout = 0.3

    def _init_extra_keys(self):
        """Internal: initializes secondary keyboard shortcuts

        The keyboard shortcuts here are not visible in the menu.
        Shortcuts assigned through the menu will take precedence.
        If we assign the same key twice, the last one will work.
        """
        k = self.app.kbm.add_extra_key

        k('bracketleft', 'Smaller')  # GIMP, Photoshop, Painter
        k('bracketright', 'Bigger')  # GIMP, Photoshop, Painter
        k('<control>bracketleft', 'RotateLeft')  # Krita
        k('<control>bracketright', 'RotateRight')  # Krita
        k('less', 'LessOpaque')  # GIMP
        k('greater', 'MoreOpaque')  # GIMP
        k('equal', 'ZoomIn')  # (on US keyboard next to minus)
        k('comma', 'Smaller')  # Krita
        k('period', 'Bigger')  # Krita

        k('BackSpace', 'ClearLayer')

        k('<control>z', 'Undo')
        k('<control>y', 'Redo')
        k('<control><shift>z', 'Redo')
        k('<control>w', lambda(action): self.app.drawWindow.quit_cb())
        k('KP_Add', 'ZoomIn')
        k('KP_Subtract', 'ZoomOut')
        k('KP_4', 'RotateLeft')  # Blender
        k('KP_6', 'RotateRight')  # Blender
        k('KP_5', 'ResetRotation')
        k('plus', 'ZoomIn')
        k('minus', 'ZoomOut')
        k('<control>plus', 'ZoomIn')  # Krita
        k('<control>minus', 'ZoomOut')  # Krita
        k('bar', 'SymmetryActive')

        k('Left', lambda(action): self.pan(self.PAN_LEFT))
        k('Right', lambda(action): self.pan(self.PAN_RIGHT))
        k('Down', lambda(action): self.pan(self.PAN_DOWN))
        k('Up', lambda(action): self.pan(self.PAN_UP))

        k('<control>Left', 'RotateLeft')
        k('<control>Right', 'RotateRight')

    ## Command history traversal actions

    def undo_cb(self, action):
        """Undo action callback"""
        self.model.undo()

    def redo_cb(self, action):
        """Redo action callback"""
        self.model.redo()

    def _update_command_stack_actions(self, *_ignored):
        """Update the undo and redo actions"""
        stack = self.model.command_stack
        draw_window = self.app.drawWindow
        ag = self.action_group

        # Icon names
        style_state = draw_window.get_style_context().get_state()
        try:  # GTK 3.8+
            if style_state & gtk.StateFlags.DIR_LTR:
                direction = 'ltr'
            else:
                direction = 'rtl'
        except AttributeError:
            # Deprecated in 3.8
            if draw_window.get_direction() == gtk.TextDirection.LTR:
                direction = 'ltr'
            else:
                direction = 'rtl'
        undo_icon_name = "mypaint-undo-%s-symbolic" % (direction,)
        redo_icon_name = "mypaint-redo-%s-symbolic" % (direction,)

        # Undo
        undo_action = ag.get_action("Undo")
        undo_action.set_sensitive(len(stack.undo_stack) > 0)
        undo_action.set_icon_name(undo_icon_name)
        if len(stack.undo_stack) > 0:
            cmd = stack.undo_stack[-1]
            desc = _("Undo %s") % cmd.display_name
        else:
            desc = _("Undo")  # Used when initializing the prefs dialog
        undo_action.set_label(desc)
        undo_action.set_tooltip(desc)

        # Redo
        redo_action = ag.get_action("Redo")
        redo_action.set_sensitive(len(stack.redo_stack) > 0)
        redo_action.set_icon_name(redo_icon_name)
        if len(stack.redo_stack) > 0:
            cmd = stack.redo_stack[-1]
            desc = _("Redo %s") % cmd.display_name
        else:
            desc = _("Redo")  # Used when initializing the prefs dialog
        redo_action.set_label(desc)
        redo_action.set_tooltip(desc)

    ## Event handling

    def button_press_cb(self, tdw, event):
        """Handles button press events received on a canvas"""
        # User-configurable switching between modes, menu popups etc.
        mode = self.modes.top
        consider_mode_switch = (
            mode.supports_button_switching
            and not getattr(mode, 'in_drag', False)
            and (
                event.button == 1
                or not (event.state & gdk.BUTTON1_MASK)
            ))
        mon = self.app.device_monitor
        dev = event.get_source_device()
        dev_settings = mon.get_device_settings(dev)
        if consider_mode_switch:
            buttonmap = self.app.button_mapping
            modifiers = event.state & gtk.accelerator_get_default_mod_mask()
            button = event.button
            action_names = [buttonmap.lookup(modifiers, button)]

            # Allow button 1 to initiate switches of mode as button 2 if
            # the device is navigation-only. This allows single-finger
            # panning with specially configured touchscreens while we're
            # not handling touch separately. Remove this when we
            # implement real touch event support.
            if dev_settings.usage == gui.device.AllowedUsage.NAVONLY:
                if button == 1:
                    action_names.insert(0, buttonmap.lookup(modifiers, 2))

            for action_name in action_names:
                # Forbid actions not named in the whitelist, if it's defined
                if action_name is not None:
                    if len(mode.permitted_switch_actions) > 0:
                        if action_name not in mode.permitted_switch_actions:
                            action_name = None
                # Perform allowed action if one was looked up
                if action_name is not None:
                    return self._dispatch_named_action(None, tdw, event,
                                                       action_name)

        # User-configurable forbidding of particular devices
        dev_usage_mask = dev_settings.usage_mask
        if not (dev_usage_mask & mode.pointer_behavior):
            return True

        # Normal event dispatch to the top mode on the mode stack
        return CanvasController.button_press_cb(self, tdw, event)

    def button_release_cb(self, tdw, event):
        """Handles button release events received on a canvas"""
        # User-configurable forbidding of particular devices
        mode = self.modes.top
        mon = self.app.device_monitor
        dev = event.get_source_device()
        dev_usage_mask = mon.get_device_settings(dev).usage_mask
        if not (dev_usage_mask & mode.pointer_behavior):
            return True
        # Normal event dispatch
        return CanvasController.button_release_cb(self, tdw, event)

    def motion_notify_cb(self, tdw, event):
        """Handles motion-notify events received on a canvas"""
        mode = self.modes.top
        mon = self.app.device_monitor
        dev = event.get_source_device()
        dev_usage_mask = mon.get_device_settings(dev).usage_mask
        if not (dev_usage_mask & mode.pointer_behavior):
            return True
        # Normal event dispatch
        CanvasController.motion_notify_cb(self, tdw, event)
        return False  # XXX don't consume motions to allow workspace autohide

    def scroll_cb(self, tdw, event):
        """Handles scroll events received on a canvas"""
        mode = self.modes.top
        mon = self.app.device_monitor
        dev = event.get_source_device()
        dev_usage_mask = mon.get_device_settings(dev).usage_mask
        if not (dev_usage_mask & mode.scroll_behavior):
            return True
        CanvasController.scroll_cb(self, tdw, event)

    def key_press_cb(self, win, tdw, event):
        """Handles key-press events received on the main window"""
        # User-configurable switching between modes, menu popups etc.
        mode = self.modes.top
        consider_mode_switch = (
            mode.supports_button_switching
            and not getattr(mode, 'in_drag', False)
            )
        if consider_mode_switch:
            # Naively pick an action based on the button map
            buttonmap = self.app.button_mapping
            action_name = None
            mods = self.get_current_modifiers()
            is_modifier = (
                event.is_modifier
                or (mods != 0 and event.keyval != keysyms.space)
                )
            if is_modifier:
                # If the keypress is a modifier only, determine the
                # modifier mask a subsequent Button1 press event would
                # get. This is used for early spring-loaded mode
                # switching.
                action_name = buttonmap.get_unique_action_for_modifiers(mods)
                # Only mode-based immediate dispatch is allowed, however.
                # Might relax this later.
                if action_name is not None:
                    if not action_name.endswith("Mode"):
                        action_name = None
            else:
                # Strategy 2: pretend that the space bar is really button 2.
                if event.keyval == keysyms.space:
                    action_name = buttonmap.lookup(mods, 2)

            # Forbid actions not named in the whitelist, if it's defined
            if len(mode.permitted_switch_actions) > 0:
                if action_name not in mode.permitted_switch_actions:
                    action_name = None

            # If we found something to do, dispatch;
            if action_name is not None:
                return self._dispatch_named_action(win, tdw, event, action_name)

            # Explain what's possible from here with some extra
            # modifiers and button presses.
            self._update_key_pressed_status_message()

            # TODO: Maybe display the inactive cursor belonging to the
            # TODO:   button1 binding for these modifiers. Blocker: need
            # TODO:   to do it without instantiating the handler class.
            #btn1_action_name = buttonmap.lookup(mods, 1)
            #btn1_handler_type, btn1_handler = gui.buttonmap.get_handler_object(
            #    self.app,
            #    btn1_action_name,
            #    )
            #if btn1_handler_type == 'mode_class':
            #    assert issubclass(btn1_handler, gui.mode.DragMode)
            #    btn1_cursor = btn1_handler.inactive_cursor    # fails.
            #    if btn1_cursor:
            #        self.tdw.set_override_cursor(btn1_cursor)

        # Normal event dispatch
        return CanvasController.key_press_cb(self, win, tdw, event)

    def key_release_cb(self, win, tdw, event):
        self._update_key_pressed_status_message()
        return CanvasController.key_release_cb(self, win, tdw, event)

    def _dispatch_named_action(self, win, tdw, event, action_name):
        """Dispatch an action looked up via the buttonmap"""
        app = self.app
        drawwindow = app.drawWindow
        if action_name == 'ShowPopupMenu':
            # Unfortunately still a special case.
            # Just firing the action doesn't work well with pads which fire a
            # button-release event immediately after the button-press.
            # Name it after the action however, in case we find a fix.
            drawwindow.show_popupmenu(event=event)
            return True
        handler_type, handler = gui.buttonmap.get_handler_object(app, action_name)
        if handler_type == 'mode_class':
            # Transfer control to another mode temporarily.
            assert issubclass(handler, gui.mode.DragMode)
            if issubclass(handler, gui.mode.OneshotDragMode):
                mode = handler(temporary_activation=True)
            else:
                mode = handler()
            self.modes.push(mode)
            if win is not None:
                return mode.key_press_cb(win, tdw, event)
            else:
                return mode.button_press_cb(tdw, event)
        elif handler_type == 'popup_state':
            # Still needed. The code is more tailored to MyPaint's
            # purposes. The names are action names, but have the more
            # tailored popup states code shadow generic action activation.
            if win is not None:
                # WORKAROUND: dispatch keypress events via the kbm so it can
                # keep track of pressed-down keys. Popup states become upset if
                # this doesn't happen: https://gna.org/bugs/index.php?20325
                action = app.find_action(action_name)
                return app.kbm.activate_keydown_event(action, event)
            else:
                # Pointer: popup states handle these themselves sanely.
                handler.activate(event)
                return True
        elif handler_type == 'gtk_action':
            # Generic named action activation. GtkActions trigger without
            # event details, so they're less flexible.
            # Hack: Firing the action in an idle handler helps with
            # actions that are sensitive to immediate button-release
            # events. But not ShowPopupMenu, sadly: we'd break button
            # hold behaviour for more reasonable devices if we used
            # this trick.
            gobject.idle_add(handler.activate)
            return True
        else:
            return False

    def _get_key_pressed_status_message_context_id(self):
        statusbar = self.app.statusbar
        try:
            context_id = self.__key_pressed_msg_statusbar_context
        except AttributeError:
            context_id = statusbar.get_context_id("key-pressed-msg")
            self.__key_pressed_msg_statusbar_context = context_id
        return context_id

    def get_current_modifiers(self):
        """Returns the current set of modifier keys as a Gdk bitmask.

        :returns: The current set of modifier keys.
        :rtype: Gdk.ModifierType

        This method should only be used in

        * Handlers for keypress events
          when the key in question is itself a modifier,
        * Handlers of multiple types of event (both key and pointer),
        * When the triggering event simply isn't available.

        Normal pointer button event handling should use
        ``event.state & gtk.accelerator_get_default_mod_mask()``
        instead.

        """
        win = self.tdw.get_window()
        display = self.tdw.get_display()
        devmgr = display and display.get_device_manager() or None
        coredev = devmgr and devmgr.get_client_pointer() or None
        if coredev and win:
            win_, x, y, mask = win.get_device_position(coredev)
            return mask & gtk.accelerator_get_default_mod_mask()
        return gdk.ModifierType(0)

    def _update_key_pressed_status_message(self):
        """Update app statusbar to explain what modes are reachable"""
        context_id = self._get_key_pressed_status_message_context_id()
        statusbar = self.app.statusbar
        statusbar.remove_all(context_id)

        btn_map = self.app.button_mapping
        mods = self.get_current_modifiers()
        if mods == 0:
            return
        poss_list = btn_map.lookup_possibilities(mods)
        if not poss_list:
            return
        poss_list.sort()
        poss_msgs = []
        current_mode = self.modes.top
        permitted_action_names = current_mode.permitted_switch_actions
        for pmods, button, action_name in poss_list:
            # Filter by the class's whitelist, if it's set
            if permitted_action_names:
                if action_name not in permitted_action_names:
                    continue
            # Don't repeat what's currently held
            pmods = pmods & ~mods
            label = gui.buttonmap.button_press_displayname(button, pmods, True)
            mode_class = gui.mode.ModeRegistry.get_mode_class(action_name)
            mode_desc = None
            if mode_class:
                mode_desc = mode_class.get_name()
            else:
                action = self.app.find_action(action_name)
                if action:
                    mode_desc = action.get_label()
            if mode_desc:
                #TRANSLATORS: Statusbar message explaining button and modifier
                #TRANSLATORS: combinations used to access modes/tools/actions.
                #TRANSLATORS: "With <current-modifiers> held down: <list>"
                msg = _(u"{button_combination} is {resultant_action}").format(
                    button_combination=label,
                    resultant_action=mode_desc,
                    )
                poss_msgs.append(msg)
        if not poss_msgs:
            return
        #TRANSLATORS: "With <current-modifiers> held down: <separated-list>"
        #TRANSLATORS: Action names may contain coordinating conjunctions such
        #TRANSLATORS: as the English "and", so use appropriate punctuation or
        #TRANSLATORS: wording for the separator. Also a little more spacing
        #TRANSLATORS: than normal looks good here.
        sep = _(";  ")
        msg = _("With {modifiers} held down:  {button_actions}.").format(
            modifiers=gtk.accelerator_get_label(0, mods),
            button_actions=sep.join(poss_msgs),
            )
        self.app.statusbar.push(context_id, msg)

    ## Copy/Paste

    def _get_clipboard(self):
        """Internal: return the GtkClipboard for the current display"""
        display = self.tdw.get_display()
        cb = gtk.Clipboard.get_for_display(display, gdk.SELECTION_CLIPBOARD)
        return cb

    def copy_cb(self, action):
        """``CopyLayer`` GtkAction callback: copy layer to clipboard"""
        # use the full document bbox, so we can paste layers back to the
        # correct position
        bbox = self.model.get_bbox()
        if bbox.w == 0 or bbox.h == 0:
            logger.error("Empty document, nothing copied")
            return
        rootstack = self.model.layer_stack
        pixbuf = rootstack.current.render_as_pixbuf(*bbox, alpha=True)
        cb = self._get_clipboard()
        cb.set_image(pixbuf)

    def paste_cb(self, action):
        """``PasteLayer`` GtkAction callback: replace layer with clipboard"""
        cb = self._get_clipboard()

        def callback(clipboard, pixbuf, junk):
            if not pixbuf:
                logger.error("The clipboard does not contain "
                             "any image to paste!")
                return
            # paste to the upper left of our doc bbox (see above)
            x, y, w, h = self.model.get_bbox()
            self.model.load_layer_from_pixbuf(pixbuf, x, y)
        cb.request_image(callback, None)

    ## Frame manipulation actions

    def trim_layer_cb(self, action):
        """Trim Layer action: discard tiles outside the frame"""
        self.model.trim_current_layer()

    def _update_trim_layer_action(self, *_ignored):
        """Updates the Trim Layer action's sensitivity"""
        app = self.app
        rootstack = self.model.layer_stack
        current = rootstack.current
        can_trim = current is not rootstack and current.get_trimmable()
        app.find_action("TrimLayer").set_sensitive(can_trim)

    def toggle_frame_cb(self, action):
        """Frame Enabled toggle callback"""
        model = self.model
        enabled = bool(model.frame_enabled)
        desired = bool(action.get_active())
        if enabled != desired:
            model.set_frame_enabled(desired, user_initiated=True)

    def _frame_enabled_changed_cb(self, model, enabled):
        """Invoked when the frame changes"""
        action = self.app.find_action("FrameToggle")
        if bool(action.get_active()) != bool(enabled):
            action.set_active(enabled)

    ## Layer and stroke picking

    def pick_context(self, x, y, action=None):
        """Picks layer and brush

        :param int x: X coord for pick, in the model's coordinate space
        :param int y: Y coord for pick, in the model's coordinate space
        :param Gdk.Action action: initiating action

        If the document has a pickable layer which has a brushstroke
        under the pick position, that layer is selected, and the
        brushstroke's settings are assigned to the current brush.

        The initiating action is used for coordinating keyboard releases
        ending the state. See gui.stategroup.

        """
        layers = self.model.layer_stack
        old_path = layers.current_path
        for c_path, c_layer in self._layer_picking_iter():
            if not self._layer_is_pickable(c_path, (x, y)):
                continue
            self.model.select_layer(path=c_path)
            if c_path != old_path:
                self.layerblink_state.activate()
            # Find the most recent (last) stroke at the pick point
            si = layers.current.get_stroke_info_at(x, y)
            if si:
                self.app.restore_brush_from_stroke_info(si)
                corners = self.tdw.get_corners_model_coords()
                bbox = lib.helpers.rotated_rectangle_bbox(corners)
                self.strokeblink_state.activate(
                    action,
                    strokeshape=si,
                    bbox=bbox,
                    center=(x, y),
                )
            return

    def pick_layer(self, x, y, action=None):
        """Picks layer only

        :param int x: X coord for pick, in the model's coordinate space
        :param int y: Y coord for pick, in the model's coordinate space
        :param Gdk.Action action: initiating action

        If the document has a pickable layer under the pick position,
        that layer is selected. Fn no layer is pickable there, the
        bottom layer is selected instead.

        The initiating action is used for coordinating keyboard releases
        ending the state. See gui.stategroup if you dare.

        """
        for p_path, p_layer in self._layer_picking_iter():
            if not self._layer_is_pickable(p_path, (x, y)):
                continue
            self.model.select_layer(path=p_path)
            self.layerblink_state.activate(action)
            return
        self.model.select_layer(path=(0,))
        self.layerblink_state.activate(action)

    def _layer_is_pickable(self, path, pos=None):
        """True if a (leaf) layer can be picked

        :param path: Layer path to the layer to be tested.
        :param pos: Optional (x,y) position to test for opacity.
        """
        stack = self.model.layer_stack
        while len(path) > 0:
            layer = stack.deepget(path, None)
            if layer is None:
                return False
            if layer.locked or not layer.visible:
                return False
            # Opacity cutoff. Opacity of the stroke is relevant if this
            # is a leaf layer.
            opacity = layer.effective_opacity
            if pos is not None:
                x, y = pos
                opacity *= layer.get_alpha(x, y, self.PICKING_RADIUS)
                pos = None
            # However the parent chain's opacity must be sufficiently
            # high all the way through for picking to work.
            if opacity < self.MIN_PICKING_OPACITY:
                return False
            path = path[:-1]
        return True

    def _layer_picking_iter(self):
        """Enumerates leaf layers in picking order, with paths"""
        layer_stack = self.model.layer_stack
        layers_enum = layer_stack.deepenumerate()
        parents = set()
        for path, layer in layers_enum:
            if path in parents:
                continue
            parent_path = path[:-1]
            parents.add(parent_path)
            yield (path, layer)

    ## Layer action callbacks

    def clear_layer_cb(self, action):
        """``ClearLayer`` GtkAction callback"""
        self.model.clear_current_layer()

    def remove_layer_cb(self, action):
        """``RemoveLayer`` GtkAction callback"""
        self.model.remove_current_layer()

    def _update_current_layer_actions(self, *_ignored):
        """Update sensitivity of actions working on the current layer"""
        app = self.app
        rootstack = self.model.layer_stack
        have_current = bool(rootstack.current_path)
        current_layer_action_names = [
            "RemoveLayer",
            "ClearLayer",
            "DuplicateLayer",
            "NewPaintingLayerAbove",  # but not below so the button still works
            "LayerMode",  # the modes submenu
            "RenameLayer",
            "LayerVisibleToggle",
            "LayerLockedToggle",
            "LayerOpacityMenu",
            "IncreaseLayerOpacity",
            "DecreaseLayerOpacity",
            "CopyLayer",
        ]
        for name in current_layer_action_names:
            app.find_action(name).set_sensitive(have_current)

    def normalize_layer_mode_cb(self, action):
        """``NormalizeLayerMode`` GtkAction callback"""
        self.model.normalize_layer_mode()

    def _update_normalize_layer_action(self, *_ignored):
        """Updates the Normalize Layer Mode action's sensitivity"""
        app = self.app
        rootstack = self.model.layer_stack
        current = rootstack.current
        can_normalize = (current is not rootstack
                         and current.get_mode_normalizable())
        app.find_action("NormalizeLayerMode").set_sensitive(can_normalize)

    ## Layer selection (current layer path in the tree)

    def select_layer_below_cb(self, action):
        """``SelectLayerBelow`` GtkAction callback"""
        layers = self.model.layer_stack
        path = layers.get_current_path()
        path = layers.path_below(path)
        if path:
            self.model.select_layer(path=path)
        self.layerblink_state.activate(action)

    def select_layer_above_cb(self, action):
        """``SelectLayerAbove`` GtkAction callback"""
        layers = self.model.layer_stack
        path = layers.get_current_path()
        path = layers.path_above(path)
        if path:
            self.model.select_layer(path=path)
        self.layerblink_state.activate(action)

    def _update_layer_select_actions(self, *_ignored):
        """Updates the Select Layer Above/Below actions"""
        app = self.app
        root = self.model.layer_stack
        current_path = root.current_path
        if current_path:
            has_predecessor = bool(root.path_above(current_path))
            has_successor = bool(root.path_below(current_path))
        else:
            has_predecessor = False
            has_successor = False
        app.find_action("SelectLayerAbove").set_sensitive(has_predecessor)
        app.find_action("SelectLayerBelow").set_sensitive(has_successor)

    ## Current layer's opacity

    def layer_increase_opacity(self, action):
        """``IncreaseLayerOpacity`` GtkAction callback"""
        rootstack = self.model.layer_stack
        if rootstack.current is rootstack:
            return
        opacity = rootstack.current.opacity
        opacity = clamp(opacity + self.OPACITY_STEP, 0.0, 1.0)
        self.model.set_current_layer_opacity(opacity)

    def layer_decrease_opacity(self, action):
        """``DecreaseLayerOpacity`` GtkAction callback"""
        rootstack = self.model.layer_stack
        if rootstack.current is rootstack:
            return
        opacity = rootstack.current.opacity
        opacity = clamp(opacity - self.OPACITY_STEP, 0.0, 1.0)
        self.model.set_current_layer_opacity(opacity)

    ## Global layer stack toggles

    def current_layer_solo_toggled_cb(self, action):
        """``SoloLayer`` GtkToggleAction callback

        Toggles between showing just the current layer (regardless of its
        visibility flag) and all visible layers.
        """
        self.model.layer_stack.current_layer_solo = action.get_active()

    def _update_layer_solo_toggle(self, *_ignored):
        """Updates the Layer Solo toggle action from the model"""
        root = self.model.layer_stack
        action = self.app.find_action("SoloLayer")
        state = root.current_layer_solo
        if bool(action.get_active()) != state:
            action.set_active(state)

    def show_background_toggle_cb(self, action):
        """``ShowBackgroundToggle`` GtkToggleAction callback"""
        layers = self.model.layer_stack
        if bool(layers.background_visible) != bool(action.get_active()):
            layers.background_visible = action.get_active()

    def _update_show_background_toggle(self, *_ignored):
        """Updates the Show Background toggle action from the model"""
        root = self.model.layer_stack
        action = self.app.find_action("ShowBackgroundToggle")
        state = root.background_visible
        if bool(action.get_active()) != state:
            action.set_active(state)

    ## Background layer

    def reset_background(self):
        """Loads the default background layer."""

        # Load the default background image if one exists
        layer_stack = self.model.layer_stack
        for datapath in [self.app.user_datapath, self.app.datapath]:
            bg_path = os.path.join(
                datapath,
                gui.backgroundwindow.BACKGROUNDS_SUBDIR,
                gui.backgroundwindow.DEFAULT_BACKGROUND,
            )
            if not os.path.exists(bg_path):
                continue
            bg, errors = gui.backgroundwindow.load_background(bg_path)
            if bg:
                layer_stack.set_background(bg, make_default=True)
                logger.info("Initialized background from %r", bg_path)
                return
            else:
                logger.warning(
                    "Failed to load saved default background image %r",
                    bg_path,
                )
                if errors:
                    for error in errors:
                        logger.warning("warning: %r", error)

        # Otherwise, try to use a sensible fallback background image.
        bg_path = os.path.join(
            self.app.datapath,
            gui.backgroundwindow.BACKGROUNDS_SUBDIR,
            gui.backgroundwindow.FALLBACK_BACKGROUND,
        )
        bg, errors = gui.backgroundwindow.load_background(bg_path)
        if bg:
            layer_stack.set_background(bg, make_default=True)
            logger.info("Initialized background from %r", bg_path)
            return
        else:
            logger.warning(
                "Failed to load fallback background image %r",
                bg_path,
            )
            if errors:
                for error in errors:
                    logger.warning("warning: %r", error)

        # Double fallback. Just use a color.
        bg_color = (0xa8, 0xa4, 0x98)
        layer_stack.set_background(bg_color, make_default=True)
        logger.info("Initialized background to %r", bg_color)


    ## Layer stack order (bubbling)

    def reorder_layer_cb(self, action):
        """Changes the z-order of a layer (GtkAction callback)

        The direction the layer moves depends on the action name:
        "RaiseLayerInStack" or "LowerLayerInStack".
        """
        if action.get_name() == 'RaiseLayerInStack':
            self.model.bubble_current_layer_up()
        elif action.get_name() == 'LowerLayerInStack':
            self.model.bubble_current_layer_down()

    def _update_layer_bubble_actions(self, *_ignored):
        """Update bubble up/down actions from the model"""
        app = self.app
        root = self.model.layer_stack
        current_path = root.current_path
        if current_path:
            deep = len(current_path) > 1
            down_poss = deep or current_path[0] < len(root)-1
            up_poss = deep or current_path[0] > 0
        else:
            down_poss = False
            up_poss = False
        app.find_action("RaiseLayerInStack").set_sensitive(up_poss)
        app.find_action("LowerLayerInStack").set_sensitive(down_poss)

    ## Simple (non-toggle) layer commands

    def new_layer_cb(self, action):
        """Callback: new layer

        Where the new layer is created, and the layer's type, depends on
        the action's name.

        """
        layers = self.model.layer_stack

        layer_class = lib.layer.PaintingLayer
        layer_kwds = {}
        edit_externally = False
        if "Vector" in action.get_name():
            layer_class = lib.layer.VectorLayer
            edit_externally = True
            # The new layer will be created with an outline of a random
            # color showing the position of the view at the time it was
            # created. Its bbox encloses this outline.
            corners = self.tdw.get_corners_model_coords()
            x, y, w, h = lib.helpers.rotated_rectangle_bbox(corners)
            layer_kwds["outline"] = corners
            layer_kwds["x"] = x
            layer_kwds["y"] = y
            layer_kwds["w"] = w
            layer_kwds["h"] = h
        elif "Group" in action.get_name():
            layer_class = lib.layer.LayerStack

        path = layers.current_path
        if not path:
            path = (-1,)
        elif 'Above' in action.get_name():
            path = layers.path_above(path, insert=True)
        else:
            path = layers.path_below(path, insert=True)
        assert path is not None

        self.model.add_layer(path, layer_class=layer_class, **layer_kwds)
        self.layerblink_state.activate(action)
        if edit_externally:
            self._begin_external_layer_edit()

    def merge_layer_down_cb(self, action):
        """Action callback: squash current layer into the one below it"""
        if self.model.merge_current_layer_down():
            self.layerblink_state.activate(action)

    def merge_visible_layers_cb(self, action):
        """Action callback: squash all visible layers into one"""
        self.model.merge_visible_layers()
        self.layerblink_state.activate(action)

    def new_layer_merged_from_visible_cb(self, action):
        """Action callback: combine all visible layers into a new one"""
        self.model.new_layer_merged_from_visible()
        self.layerblink_state.activate(action)

    def _update_merge_layer_down_action(self, *_ignored):
        """Updates the layer Merge Down action's sensitivity"""
        # This may change in response to the path changing *or* the
        # mode property of the current or underlying layer changing.
        app = self.app
        rootstack = self.model.layer_stack
        current = rootstack.current_path
        can_merge = (current is not rootstack
                     and bool(rootstack.get_merge_down_target(current)))
        app.find_action("MergeLayerDown").set_sensitive(can_merge)

    def duplicate_layer_cb(self, action):
        """``DuplicateLayer`` GtkAction callback: clone the current layer"""
        self.model.duplicate_current_layer()

    def rename_layer_cb(self, action):
        """``RenameLayer`` GtkAction callback: layer rename dialog"""
        layer = self.model.layer_stack.get_current()
        if layer is self.model.layer_stack:
            return
        old_name = layer.name
        if old_name is None:
            old_name = layer.DEFAULT_NAME
        win = self.app.drawWindow
        new_name = dialogs.ask_for_name(win, _("Layer Name"), old_name)
        if new_name:
            self.model.rename_current_layer(new_name)

    ## Per-layer flag toggles

    def layer_lock_toggle_cb(self, action):
        """``LayerLockedToggle`` GtkAction callback"""
        layer = self.model.layer_stack.get_current()
        if bool(layer.locked) != bool(action.get_active()):
            self.model.set_layer_locked(action.get_active(), layer)

    def layer_visible_toggle_cb(self, action):
        """``LayerVisibleToggle`` GtkAction callback"""
        layer = self.model.layer_stack.get_current()
        if bool(layer.visible) != bool(action.get_active()):
            self.model.set_layer_visibility(action.get_active(), layer)

    def _update_layer_flag_toggles(self, *_ignored):
        """Updates ToggleActions reflecting the current layer's flags"""
        rootstack = self.model.layer_stack
        current_layer = rootstack.current
        action_updates = [
            ("LayerLockedToggle", current_layer.locked),
            ("LayerVisibleToggle", current_layer.visible),
        ]
        for action_name, model_state in action_updates:
            action = self.app.find_action(action_name)
            if bool(action.get_active()) != bool(model_state):
                action.set_active(model_state)

    ## Brush settings callbacks

    def brush_bigger_cb(self, action):
        """``Bigger`` GtkAction callback"""
        adj = self.app.brush_adjustment['radius_logarithmic']
        adj.set_value(adj.get_value() + 0.3)

    def brush_smaller_cb(self, action):
        """``Smaller`` GtkAction callback"""
        adj = self.app.brush_adjustment['radius_logarithmic']
        adj.set_value(adj.get_value() - 0.3)

    def more_opaque_cb(self, action):
        """``MoreOpaque`` GtkAction callback"""
        # FIXME: hm, looks this slider should be logarithmic?
        adj = self.app.brush_adjustment['opaque']
        adj.set_value(adj.get_value() * 1.8)

    def less_opaque_cb(self, action):
        """``MoreOpaque`` GtkAction callback"""
        adj = self.app.brush_adjustment['opaque']
        adj.set_value(adj.get_value() / 1.8)

    def brighter_cb(self, action):
        """``Brighter`` GtkAction callback: lighten the brush color"""
        # TODO: use HCY?
        h, s, v = self.app.brush.get_color_hsv()
        v += 0.08
        if v > 1.0:
            v = 1.0
        self.app.brush.set_color_hsv((h, s, v))

    def darker_cb(self, action):
        """``Darker`` GtkAction callback: darken the brush color"""
        # TODO: use HCY?
        h, s, v = self.app.brush.get_color_hsv()
        v -= 0.08
        # stop a little higher than 0.0, to avoid resetting hue to 0
        if v < 0.005:
            v = 0.005
        self.app.brush.set_color_hsv((h, s, v))

    def increase_hue_cb(self, action):
        """``IncreaseHue`` GtkAction callback: anticlockwise hue rotation"""
        # TODO: use HCY?
        h, s, v = self.app.brush.get_color_hsv()
        e = 0.015
        h = (h + e) % 1.0
        self.app.brush.set_color_hsv((h, s, v))

    def decrease_hue_cb(self, action):
        """``DecreaseHue`` GtkAction callback: clockwise hue rotation"""
        # TODO: use HCY?
        h, s, v = self.app.brush.get_color_hsv()
        e = 0.015
        h = (h - e) % 1.0
        self.app.brush.set_color_hsv((h, s, v))

    def purer_cb(self, action):
        """``Purer`` GtkAction callback: make the brush color less grey"""
        # TODO: use HCY?
        h, s, v = self.app.brush.get_color_hsv()
        s += 0.08
        if s > 1.0:
            s = 1.0
        self.app.brush.set_color_hsv((h, s, v))

    def grayer_cb(self, action):
        """``Grayer`` GtkAction callback: make the brush color more grey"""
        # TODO: use HCY?
        h, s, v = self.app.brush.get_color_hsv()
        s -= 0.08
        # stop a little higher than 0.0, to avoid resetting hue to 0
        if s < 0.005:
            s = 0.005
        self.app.brush.set_color_hsv((h, s, v))

    ## Brush settings

    def brush_reload_settings(self, cnames=None):
        """Reset some or all brush settings to their saved values

        :param cname: Setting names to reset; default is all settings
        :type cname: Iterable of setting cnames.
        """
        app = self.app
        bm = app.brushmanager
        parent_brush = bm.get_parent_brush(brushinfo=app.brush)
        if parent_brush is None:
            return
        if cnames is None:
            bm.select_brush(parent_brush)
        else:
            parent_binfo = parent_brush.get_brushinfo()
            for cname in cnames:
                parent_value = parent_binfo.get_base_value(cname)
                adj = app.brush_adjustment[cname]
                adj.set_value(parent_value)
        app.brushmodifier.normal_mode.activate()

    def brush_reload_cb(self, action):
        """``BrushReload`` GtkAction callback. Reload all brush settings."""
        self.brush_reload_settings()

    def brush_is_modified(self):
        """True if the brush was modified from its saved state"""
        current_bi = self.app.brush
        parent_b = self.app.brushmanager.get_parent_brush(brushinfo=current_bi)
        if parent_b is None:
            return True
        return not parent_b.brushinfo.matches(current_bi)

    def _brush_settings_changed_cb(self, *a):
        """Internal callback: updates the UI when brush settings change"""
        reset_action = self.app.find_action("BrushReload")
        if self.brush_is_modified():
            if not reset_action.get_sensitive():
                reset_action.set_sensitive(True)
        else:
            if reset_action.get_sensitive():
                reset_action.set_sensitive(False)

    ## Brushkey callbacks

    def context_cb(self, action):
        """GtkAction callback for various brushkey operations"""
        name = action.get_name()
        store = False
        bm = self.app.brushmanager
        if name == 'ContextStore':
            context = bm.selected_context
            if not context:
                logger.error('No context was selected, '
                             'ignoring store command.')
                return
            store = True
        else:
            if name.endswith('s'):
                store = True
                name = name[:-1]
            i = int(name[-2:])
            context = bm.contexts[i]
        bm.selected_context = context
        if store:
            context.brushinfo = self.app.brush.clone()
            context.preview = bm.selected_brush.preview
            context.save()
        else:
            # restore brush
            bm.select_brush(context)
            if self.app.preferences['misc.context_restores_color']:
                # restore color
                self.app.brushmodifier.restore_context_of_selected_brush()

    def context_toggle_color_cb(self, action):
        """GtkToggleAction callback for whether brushkeys restore color"""
        value = bool(action.get_active())
        self.app.preferences['misc.context_restores_color'] = value

    ## UI feedback for current layer/stroke

    def strokeblink_state_enter(self, strokeshape, bbox, center):
        """`gui.stategroup.State` entry callback for blinking a stroke"""
        overlay = lib.layer.SurfaceBackedLayer()
        overlay.load_from_strokeshape(strokeshape, bbox=bbox, center=center)
        self.tdw.overlay_layer = overlay
        bbox = tuple(overlay.get_bbox())
        self.model.canvas_area_modified(*bbox)

    def strokeblink_state_leave(self, reason):
        """`gui.stategroup.State` leave callback for blinking a stroke"""
        if self.tdw.overlay_layer is None:
            return
        bbox = self.tdw.overlay_layer.get_bbox()
        self.tdw.overlay_layer = None
        self.model.canvas_area_modified(*bbox)

    def layerblink_state_enter(self):
        """`gui.stategroup.State` entry callback for blinking a layer"""
        layers = self.model.layer_stack
        layers.current_layer_previewing = True

    def layerblink_state_leave(self, reason):
        """`gui.stategroup.State` leave callback for blinking a layer"""
        layers = self.model.layer_stack
        layers.current_layer_previewing = False

    ## Viewport manipulation

    def pan(self, direction):
        """Handles panning (scrolling) in increments.

        :param direction: direction of panning
        :type direction: `PAN_LEFT`, `PAN_RIGHT`, `PAN_UP`, or `PAN_DOWN`
        """
        allocation = self.tdw.get_allocation()
        step = min((allocation.width, allocation.height)) * self.PAN_STEP
        if direction == self.PAN_LEFT:
            self.tdw.scroll(-step, 0, ongoing=False)
        elif direction == self.PAN_RIGHT:
            self.tdw.scroll(+step, 0, ongoing=False)
        elif direction == self.PAN_UP:
            self.tdw.scroll(0, -step, ongoing=False)
        elif direction == self.PAN_DOWN:
            self.tdw.scroll(0, +step, ongoing=False)
        else:
            raise TypeError('unsupported pan() direction=%s' % direction)
        self.notify_view_changed()

    def zoom(self, direction, center=CENTER_ON_POINTER):
        """Handles zoom in increments.

        Zooms the doc's TDW by a set amount, either in or out.

        :param direction: direction of zoom
        :type direction: `ZOOM_INWARDS` or `ZOOM_OUTWARDS`
        :param center: zoom center
        :type center: tuple ``(x, y)`` in model coords, or `CENTER_ON_POINTER`
            or `CENTER_ON_VIEWPORT`
        """

        if center == self.CENTER_ON_POINTER:
            etime, ex, ey = self.get_last_event_info(self.tdw)
            center = (ex, ey)
        elif center == self.CENTER_ON_VIEWPORT:
            center = self.tdw.get_center()

        try:
            zoom_index = self.zoomlevel_values.index(self.tdw.scale)
        except ValueError:
            zoom_levels = self.zoomlevel_values[:]
            zoom_levels.append(self.tdw.scale)
            zoom_levels.sort()
            zoom_index = zoom_levels.index(self.tdw.scale)

        if direction == self.ZOOM_INWARDS:
            zoom_index += 1
        elif direction == self.ZOOM_OUTWARDS:
            zoom_index -= 1
        else:
            raise TypeError('unsupported zoom() direction=%s' % direction)

        if zoom_index < 0:
            zoom_index = 0
        if zoom_index >= len(self.zoomlevel_values):
            zoom_index = len(self.zoomlevel_values) - 1

        z = self.zoomlevel_values[zoom_index]
        self.tdw.set_zoom(z, center=center)
        self.notify_view_changed()

    def rotate(self, direction, center=CENTER_ON_POINTER):
        """Handles rotation in increments.

        Rotates the doc's TDW by a set amount, either left or right.

        :param direction: direction of rotation
        :type direction: `ROTATE_CLOCKWISE` or `ROTATE_ANTICLOCKWISE`
        :param center: rotation center
        :type center: tuple ``(x, y)`` in model coords, or `CENTER_ON_POINTER`
            or `CENTER_ON_VIEWPORT`
        """
        if center == self.CENTER_ON_POINTER:
            etime, ex, ey = self.get_last_event_info(self.tdw)
            center = (ex, ey)
        elif center == self.CENTER_ON_VIEWPORT:
            center = self.tdw.get_center()

        if direction == self.ROTATE_CLOCKWISE:
            step = +self.ROTATION_STEP
        elif direction == self.ROTATE_ANTICLOCKWISE:
            step = -self.ROTATION_STEP
        else:
            raise TypeError('unsupported direction=%s' % direction)
        self.tdw.rotate(
            step,
            center=center,
            ongoing=False,
        )
        self.notify_view_changed()

    def zoom_cb(self, action):
        """Callback for Zoom{In,Out} GtkActions"""
        direction = self.ZOOM_INWARDS
        if action.get_name() == 'ZoomOut':
            direction = self.ZOOM_OUTWARDS
        self.zoom(direction)

    def rotate_cb(self, action):
        """Callback for Rotate{Left,Right} GtkActions"""
        direction = self.ROTATE_CLOCKWISE
        if action.get_name() == 'RotateRight':
            direction = self.ROTATE_ANTICLOCKWISE
        self.rotate(direction)

    ## Symmetry

    def symmetry_active_toggled_cb(self, action):
        """Handle changes to the SymmetryActive toggle"""
        already_active = bool(self.model.layer_stack.symmetry_active)
        want_active = bool(action.get_active())
        if want_active and not already_active:
            alloc = self.tdw.get_allocation()
            axis_pos = self.model.layer_stack.symmetry_axis
            if axis_pos is None:
                center_disp = alloc.width/2.0, alloc.height/2.0
                center_model = self.tdw.display_to_model(*center_disp)
                axis_pos = center_model[0]
                self.model.layer_stack.symmetry_axis = axis_pos
        if want_active != already_active:
            self.model.layer_stack.symmetry_active = want_active

    def _symmetry_state_changed_cb(self, layerstack, active, x):
        """Update the SymmetryActive toggle on model state changes"""
        symm_toggle = self.action_group.get_action("SymmetryActive")
        symm_toggle_active = bool(symm_toggle.get_active())
        model_symm_active = bool(active)
        if symm_toggle_active != model_symm_active:
            symm_toggle.set_active(model_symm_active)

    ## More viewport manipulation

    def mirror_horizontal_cb(self, action):
        """Flips the viewport from left to right"""
        self.tdw.mirror()
        self.notify_view_changed()

    def mirror_vertical_cb(self, action):
        """Flips the viewport from top to bottom"""
        self.tdw.rotate(math.pi)
        self.tdw.mirror()
        self.notify_view_changed()

    def reset_view_cb(self, action):
        """Action callback: resets various aspects of the view.

        The reset chosen depends on the action's name.
        """
        if action is None:
            action_name = None
        else:
            action_name = action.get_name()
        zoom = mirror = rotation = False
        if action_name is None or 'View' in action_name:
            zoom = mirror = rotation = True
        elif 'Rotation' in action_name:
            rotation = True
        elif 'Zoom' in action_name:
            zoom = True
        elif 'Mirror' in action_name:
            mirror = True
        if rotation or zoom or mirror:
            self.reset_view(rotation, zoom, mirror)

    def reset_view(self, rotation=False, zoom=False, mirror=False):
        """Programatically resets the view to the defaults.

        :param rotation: Reset rotation to zero.
        :param zoom: Reset rotation to the prefs default zoom.
        :param mirror: Turn mirroring off
        """
        if rotation:
            self.tdw.set_rotation(0.0)
        if zoom:
            default_zoom = self.app.preferences['view.default_zoom']
            self.tdw.set_zoom(default_zoom)
        if mirror:
            self.tdw.set_mirrored(False)
        if rotation and zoom and mirror:
            self.tdw.recenter_document()
        if rotation or zoom or mirror:
            self.notify_view_changed()

    def fit_view_toggled_cb(self, action):
        """Callback: toggles between fit-document and the current view.

        This callback saves to and restores from the saved view. If the action
        is toggled off when there is a saved view, the saved view will be
        restored.
        """
        # Note: saved_view must be set to None before notify_view_changed() is
        # called by anything - we use it as an interlock.
        if action.get_active():
            view = self.tdw.get_transformation()
            self.saved_view = None
            self.fit_view()
            self.saved_view = view
        elif self.saved_view is not None:
            view = self.saved_view
            self.tdw.set_transformation(self.saved_view)
            self.saved_view = None
            self.notify_view_changed(immediate=True)

    def fit_view(self):
        """Programatically fits the view to the document"""
        bbox = tuple(self.tdw.doc.get_effective_bbox())
        w, h = bbox[2:4]
        if w == 0:
            # When there is nothing on the canvas reset zoom to default.
            self.reset_view(True, True, True)
            return
        # Otherwise, zoom and transform to fit the bounding box, while
        # preserving the user's rotation and mirroring settings.
        allocation = self.tdw.get_allocation()
        w1, h1 = allocation.width, allocation.height
        # Store radians and reset rotation to zero.
        radians = self.tdw.rotation
        self.tdw.set_rotation(0.0)
        # Store mirror and temporarily it turn off mirror.
        mirror = self.tdw.mirrored
        self.tdw.set_mirrored(False)
        # Using w h as the unrotated bbox, calculate the bbox of the
        # rotated doc.
        cos = math.cos(radians)
        sin = math.sin(radians)
        wcos = w * cos
        hsin = h * sin
        wsin = w * sin
        hcos = h * cos
        # We only need to calculate the positions of two corners of the
        # bbox since it is centered and symetrical, but take the max
        # value since during rotation one corner's distance along the
        # x axis shortens while the other lengthens. Same for the y axis.
        x = max(abs(wcos - hsin), abs(wcos + hsin))
        y = max(abs(wsin + hcos), abs(wsin - hcos))
        # Compare the doc and window dimensions and take the best fit
        zoom = min((w1-20)/x, (h1-20)/y)
        # Reapply all transformations
        self.tdw.recenter_document()  # Center image
        self.tdw.set_rotation(radians)  # reapply canvas rotation
        self.tdw.set_mirrored(mirror)  # reapply mirror
        self.tdw.set_zoom(zoom)  # Set new zoom level
        # Notify interested parties
        self.notify_view_changed(immediate=True)

    def notify_view_changed(self, prioritize=False, immediate=False):
        """Notifies all parties interested in the view having changed.

        These can be slightly expensive, so the callbacks are rate limited
        using an idle routine when called with default args. All callbacks in
        `self.view_changed_observers` are guaranteed to be called shortly after
        this method is called, with a ref to this Document.

        The default idle priority is intentionally very low. To raise it, set
        `prioritize` to true. This is designed to be used only when this
        notification indirectly updates a graphical element which is directly
        under the pointer, or otherwise where the user is looking.
        """
        if immediate:
            if self._view_changed_notification_srcid:
                gobject.source_remove(self._view_changed_notification_srcid)
                self._view_changed_notification_srcid = None
            self._view_changed_notification_idle_cb()
            return
        if self._view_changed_notification_srcid:
            return
        cb = self._view_changed_notification_idle_cb
        priority = gobject.PRIORITY_LOW
        if prioritize:
            priority = gobject.PRIORITY_HIGH_IDLE
        srcid = gobject.idle_add(cb, priority=priority)
        self._view_changed_notification_srcid = srcid

    def _view_changed_notification_idle_cb(self):
        """Background notifier callback used by `notify_view_changed()`"""
        for cb in self.view_changed_observers:
            cb(self)
        self._view_changed_notification_srcid = None
        return False

    def _view_changed_cb(self, doc):
        """Callback: clear saved view and reset toggles on viewport changes"""
        if not self.saved_view:
            return
        # Clear saved view first...
        self.saved_view = None
        # ... it's used as an interlock by toggle callbacks which use it.
        view_toggle_actions = ["FitView"]
        for action_name in view_toggle_actions:
            action = self.app.find_action(action_name)
            if action.get_active():
                action.set_active(False)

    ## Debugging

    def print_inputs_cb(self, action):
        """Toggles brush input printing"""
        self.model.brush.set_print_inputs(action.get_active())

    def visualize_rendering_cb(self, action):
        """Toggles highlighting of each redraw"""
        self.tdw.renderer.visualize_rendering = action.get_active()

    def no_double_buffering_cb(self, action):
        """Toggles double buffering"""
        self.tdw.renderer.set_double_buffered(not action.get_active())

    ## Model state reflection

    def _input_stroke_ended_cb(self, self_again, event):
        """Invoked after a pen-down, draw, pen-up 'input stroke'"""
        # Store device-specific brush settings at the end of the stroke,
        # not when the device changes because the user can change brush
        # radii etc. in the middle of a stroke, and because
        # device_changed_cb won't respond when the user fiddles with
        # colors, opacity and sizes via the dialogs.
        device_name = self.app.preferences.get('devbrush.last_used', None)
        if device_name is None:
            return
        bm = self.app.brushmanager
        selected_brush = bm.clone_selected_brush(name=None)  # for saving
        bm.store_brush_for_device(device_name, selected_brush)
        # However it may be better to reflect any brush settings change
        # into the last-used devbrush immediately. The UI idea here is
        # that the pointer (when you're holding the pen) is special,
        # it's the point of a real-world tool that you're dipping into a
        # palette, or modifying using the sliders.

    ## Mode flipping

    def mode_flip_action_activated_cb(self, flip_action):
        """Callback: a mode "flip" action was activated.

        :param flip_action: the gtk.Action which was activated

        Mode classes are looked up via `gui.mode.ModeRegistry` based
        on the name of the action: flip actions are named after the
        RadioActions they nominally control, with "Flip" prepended.
        Activating a FlipAction has the effect of flipping a mode off if
        it is currently active, or on if another mode is active. Mode
        flip actions are the usual actions bound to keypresses since
        being able to toggle off with the same key is useful.

        Because these modes are intended for keyboard activation, they
        are instructed to ignore the initial keyboard modifier state
        when entered.  See also: `gui.mode.DragMode`.

        """
        # If this is not the active document, dispatch the action to it.
        active_doc = Document.get_active_instance()
        if (active_doc is not None) and (active_doc is not self):
            return active_doc.mode_flip_action_activated_cb(flip_action)

        flip_action_name = flip_action.get_name()
        assert flip_action_name.startswith("Flip")
        # Find the corresponding gtk.RadioAction
        action_name = flip_action_name.replace("Flip", "", 1)
        mode_class = gui.mode.ModeRegistry.get_mode_class(action_name)
        if mode_class is None:
            warn("%r not registered: check imports" % (action_name,), Warning)
            return

        # If a mode object of this exact class is active, pop the stack.
        # Otherwise, instantiate and enter.
        if self.modes.top.__class__ is mode_class:
            self.modes.pop()
            flip_action.keyup_callback = lambda *a: None  # suppress repeats
        else:
            if issubclass(mode_class, gui.mode.OneshotDragMode):
                mode = mode_class(ignore_modifiers=True, temporary_activation=False)
            else:
                mode = mode_class(ignore_modifiers=True)
            if flip_action.keydown:
                flip_action.__pressed = True
                # Change what happens on a key-up after a short while.
                # Distinguishes long presses from short.
                timeout = getattr(mode, "keyup_timeout", 500)
                cb = self._modeflip_change_keyup_callback
                ev = gtk.get_current_event()
                if ev is not None:
                    ev = ev.copy()
                if timeout > 0:
                    # Queue a change of key-up callback after the timeout
                    gobject.timeout_add(timeout, cb, mode, flip_action, ev)

                    def _continue_mode_early_keyup_cb(*a):
                        # Record early keyup, but otherwise keep in mode
                        flip_action.__pressed = False
                    flip_action.keyup_callback = _continue_mode_early_keyup_cb
                else:
                    # Key-up exits immediately
                    def _exit_mode_early_keyup_cb(*a):
                        if mode is self.modes.top:
                            self.modes.pop()
                    flip_action.keyup_callback = _exit_mode_early_keyup_cb
            self.modes.context_push(mode)

    def _modeflip_change_keyup_callback(self, mode, flip_action, ev):
        """Changes what happens when a flip-action key is released"""
        # Changes the keyup handler to one which will pop the mode stack
        # if the mode instance is still at the top.
        if not flip_action.__pressed:
            return False

        if mode is self.modes.top:
            def _exit_mode_late_keyup_cb(*a):
                if mode is self.modes.top:
                    self.modes.pop()
            flip_action.keyup_callback = _exit_mode_late_keyup_cb

        # Could make long-presses start the drag+grab somehow, e.g.
        #if hasattr(mode, '_start_drag'):
        #    mode._start_drag(mode.doc.tdw, ev)
        return False

    ## Mode stack reflection

    def mode_radioaction_changed_cb(self, action, current_action):
        """Callback: radio action controlling the modes stack activated

        :param action: the lead gtk.RadioAction
        :param current_action: the newly active gtk.RadioAction

        Mode classes are looked up via `gui.mode.ModeRegistry` based
        on the name of the action. This action instantiates the mode and
        pushes it onto the mode stack unless the active mode is already
        an instance of the mode class.

        """
        # Update the mode stack so that its top element matches the
        # newly chosen action.
        action_name = current_action.get_name()
        mode_class = gui.mode.ModeRegistry.get_mode_class(action_name)
        if mode_class is None:
            warn("%r not registered: check imports" % (action_name,), Warning)
            return

        if self.modes.top.__class__ is not mode_class:
            if issubclass(mode_class, gui.mode.OneshotDragMode):
                mode = mode_class(temporary_activation=False)
            else:
                mode = mode_class()
            self.modes.context_push(mode)

    def _modestack_changed_cb(self, modestack, old, new):
        """Callback: make actions follow changes to the mode stack"""
        # Activate the action corresponding to the current top mode.
        logger.debug("Mode changed: %r", self.modes)
        action_name = new.ACTION_NAME
        if not action_name:
            return None
        action = self.app.builder.get_object(action_name)
        if action is not None:
            # Not every mode has a corresponding action
            if not action.get_active():
                action.set_active(True)

    ## External layer editing support

    def begin_external_layer_edit_cb(self, action):
        """Callback: edit the current layer in an external app"""
        self._begin_external_layer_edit()

    def _begin_external_layer_edit(self):
        layer = self.model.layer_stack.current
        self._layer_edit_manager.begin(layer)

    def commit_external_layer_edit_cb(self, action):
        """Callback: Commit the current layer's ongoing external edit

        Exposed as an extra action just in case automatic monitoring
        fails on a particular platform. Normally the manager commits
        saved changes automatically.

        """
        layer = self.model.layer_stack.current
        self._layer_edit_manager.commit(layer)

    def _update_external_layer_edit_actions(self, *_ignored):
        """Update the External Layer Edit actions' sensitivities"""
        app = self.app
        rootstack = self.model.layer_stack
        current = rootstack.current
        can_commit = hasattr(current, "load_from_external_edit_tempfile")
        app.find_action("BeginExternalLayerEdit").set_sensitive(can_commit)
        app.find_action("CommitExternalLayerEdit").set_sensitive(can_commit)