68
Trestle Reference Manual
Mark S. Manasse and Greg Nelson
December 1991
Systems Research Center 130 Lytton Avenue
Palo Alto, California 94301
Systems Research Center
DEC's business and technology objectives require a strong research program. The Systems Research Center (SRC) and three other research laboratories are committed to filling that need.
SRC began recruiting its first research scientists in l984 – their charter, to advance the state of knowledge in all aspects of computer systems research. Our current work includes exploring high-performance personal computing, distributed computing, programming environments, system modelling techniques, specification technology, and tightly-coupled multiprocessors.
Our approach to both hardware and software research is to create and use real systems so that we can investigate their properties fully. Complex systems cannot be evaluated solely in the abstract.
Based on this belief, our strategy is to demonstrate the technical and practical feasibility of our ideas by building prototypes and using them as daily tools. The experience we gain is useful in the short term in enabling us to refine our designs, and invaluable in the long term in helping us to advance the state of knowledge about those systems. Most of the major advances in information systems have come through this strategy, including time-sharing, the ArpaNet, and distributed personal computing.
SRC also performs work of a more mathematical flavor which complements our systems research. Some of this work is in established fields of theoretical computer science, such as the analysis of algorithms, computational geometry, and logics of programming. The rest of this work explores new ground motivated by problems that arise in our systems research.
DEC has a strong commitment to communicating the results and experience gained through pursuing these activities. The Company values the improved understanding that comes with exposing and testing our ideas within the research community. SRC will therefore report results in conferences, in professional journals, and in our research report series. We will seek users for our prototype systems among those with whom we have common research interests, and we will encourage collaboration with university researchers.
Robert W. Taylor, Director
Trestle Reference Manual
Mark S. Manasse and Greg Nelson
December, 1991
© Digital Equipment Corporation 1991
This work may not be copied or reproduced in whole or in part for any commercial
purpose. Permission to copy in whole or in part without payment of fee is granted for
nonprofit educational and research purposes provided that all such whole or partial
copies include the following: a notice that such copying is by permission of the Systems
Research Center of Digital Equipment Corporation in Palo Alto, California; an
acknowledgment of the authors and individual contributors to the work; and all
applicable portions of the copyright notice. Copying, reproducing, or republishing for
any other purpose shall require a license with payment of fee to the Systems Research
Center. All rights reserved.
Authors’ abstract
This is a reference manual for Trestle, a Modula-3 toolkit for the X window system.
Trestle is a collection of interfaces structured around a central abstract type: a “virtual bitmap terminal” or VBT, which represents a share of the workstation’s screen, keyboard, and mouse—a thing comparable to the viewers, windows, or widgets of other systems.
Trestle is included in SRC Modula-3 version 2.0, which is available via public ftp.
Trestle includes a fairly standard set of interactors, including menus, buttons, “container”
classes that provide overlapping or tiled subwindows, and “leaf” windows that display text or other data. This reference manual also specifies the interfaces that allow you to create your own window classes. Knowledge of X is not required.
A Trestle window is an object whose behavior is determined by its methods. For example, a window’s response to a mouse click is determined by calling its mouse method. This is fast becoming the standard architecture for toolkits, but Trestle carries it further than most. For example, you can change the way a Trestle window paints by overriding its paint method; this is useful for sophisticated effects like groupware.
Trestle provides a novel strategy for writing applications that are independent of the type of display screen they are running on. For example, it is easy to write a Trestle
application that can be moved back and forth between a color display and a monochrome
display where the application will look good on both.
Contents
1 Introduction 1
2 The VBT interface 7
2.1 The public methods : : : : : : : : : : : : : : : : : : : : : : : : : : 7 2.2 Screens and domains : : : : : : : : : : : : : : : : : : : : : : : : : : 8 2.3 Locking level: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 8 2.4 ScreenTypes : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 9 2.5 Splits and leaves : : : : : : : : : : : : : : : : : : : : : : : : : : : : 10 2.6 Timestamps, modifiers, mouse buttons, and cursor positions : : : : : : 10 2.7 The mouse method : : : : : : : : : : : : : : : : : : : : : : : : : : : 12 2.8 The mouse focus rule: : : : : : : : : : : : : : : : : : : : : : : : : : 12 2.9 The position method : : : : : : : : : : : : : : : : : : : : : : : : : : 13 2.10 Tracking the cursor by setting cages : : : : : : : : : : : : : : : : : : 14 2.11 The key method : : : : : : : : : : : : : : : : : : : : : : : : : : : : 16 2.12 The redisplay method : : : : : : : : : : : : : : : : : : : : : : : : : 17 2.13 The reshape method : : : : : : : : : : : : : : : : : : : : : : : : : : 18 2.14 The rescreen method : : : : : : : : : : : : : : : : : : : : : : : : : : 19 2.15 The repaint method: : : : : : : : : : : : : : : : : : : : : : : : : : : 19 2.16 About painting in general : : : : : : : : : : : : : : : : : : : : : : : 20 2.17 Scrolling (copying one part of the screen to another) : : : : : : : : : : 21 2.18 Painting textures : : : : : : : : : : : : : : : : : : : : : : : : : : : : 22 2.19 Filling and stroking paths : : : : : : : : : : : : : : : : : : : : : : : 24 2.20 Painting pixmaps : : : : : : : : : : : : : : : : : : : : : : : : : : : : 25 2.21 Painting text : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 26 2.22 Synchronization of painting requests : : : : : : : : : : : : : : : : : : 29 2.23 Screen capture : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 30 2.24 Controlling the cursor shape : : : : : : : : : : : : : : : : : : : : : : 30 2.25 Selections : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 31 2.26 Acquiring and releasing selection ownership: : : : : : : : : : : : : : 32 2.27 The miscellaneous method : : : : : : : : : : : : : : : : : : : : : : : 32 2.28 Sending miscellaneous codes: : : : : : : : : : : : : : : : : : : : : : 34 2.29 Circumventing event-time : : : : : : : : : : : : : : : : : : : : : : : 34 2.30 Communicating selection values : : : : : : : : : : : : : : : : : : : : 34 2.31 The read and write methods : : : : : : : : : : : : : : : : : : : : : : 36 2.32 Controlling the shape of a VBT : : : : : : : : : : : : : : : : : : : : 37 2.33 Putting properties on a VBT : : : : : : : : : : : : : : : : : : : : : : 37 2.34 Discarding a VBT : : : : : : : : : : : : : : : : : : : : : : : : : : : 38
i
3 The Trestle interface 39 3.1 Window placement : : : : : : : : : : : : : : : : : : : : : : : : : : : 41 3.2 Enumerating and positioning screens: : : : : : : : : : : : : : : : : : 42 3.3 Reading pixels from a screen: : : : : : : : : : : : : : : : : : : : : : 43 3.4 Checking on recent input activity : : : : : : : : : : : : : : : : : : : 43 3.5 Connecting to a window system : : : : : : : : : : : : : : : : : : : : 44
4 Splits 45
4.1 The Split interface : : : : : : : : : : : : : : : : : : : : : : : : : : : 45 4.2 The ZSplit interface : : : : : : : : : : : : : : : : : : : : : : : : : : 47 4.2.1 Inserting children : : : : : : : : : : : : : : : : : : : : : : : 48 4.2.2 Moving, lifting, and lowering children : : : : : : : : : : : : : 49 4.2.3 Mapping and unmapping children : : : : : : : : : : : : : : : 50 4.2.4 Getting domains : : : : : : : : : : : : : : : : : : : : : : : : 50 4.2.5 Moving children when the parent is reshaped : : : : : : : : : 51 4.3 The HVSplit interface : : : : : : : : : : : : : : : : : : : : : : : : : 53 4.3.1 Inserting children : : : : : : : : : : : : : : : : : : : : : : : 55 4.3.2 Adjusting the division of space: : : : : : : : : : : : : : : : : 56 4.4 The PackSplit interface: : : : : : : : : : : : : : : : : : : : : : : : : 57 4.5 The TSplit interface : : : : : : : : : : : : : : : : : : : : : : : : : : 59
5 Filters 60
5.1 The Filter interface : : : : : : : : : : : : : : : : : : : : : : : : : : : 60 5.2 The BorderedVBT interface : : : : : : : : : : : : : : : : : : : : : : 60 5.3 The RigidVBT interface : : : : : : : : : : : : : : : : : : : : : : : : 62 5.4 The HighlightVBT interface : : : : : : : : : : : : : : : : : : : : : : 63 5.5 The TranslateVBT interface : : : : : : : : : : : : : : : : : : : : : : 64 5.6 Buttons: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 65 5.7 Quick buttons : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 66 5.8 Menu Buttons : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 67 5.9 Anchor Buttons : : : : : : : : : : : : : : : : : : : : : : : : : : : : 68
6 Some useful Leaf VBTs 71
6.1 The TextVBT interface: : : : : : : : : : : : : : : : : : : : : : : : : 71 6.2 The TextureVBT interface : : : : : : : : : : : : : : : : : : : : : : : 72 6.3 The HVBar interface : : : : : : : : : : : : : : : : : : : : : : : : : : 73
7 Resources 75
7.1 The PaintOp interface : : : : : : : : : : : : : : : : : : : : : : : : : 75 7.2 The Cursor interface : : : : : : : : : : : : : : : : : : : : : : : : : : 79 7.3 The Pixmap interface: : : : : : : : : : : : : : : : : : : : : : : : : : 80 7.4 The Font interface : : : : : : : : : : : : : : : : : : : : : : : : : : : 81 7.5 The Palette interface : : : : : : : : : : : : : : : : : : : : : : : : : : 82 7.6 The ScreenType interface : : : : : : : : : : : : : : : : : : : : : : : 84
ii
7.7 Screen-dependent painting operations : : : : : : : : : : : : : : : : : 85 7.7.1 Obtaining handles from the oracle : : : : : : : : : : : : : : : 85 7.7.2 The handle object : : : : : : : : : : : : : : : : : : : : : : : 87 7.8 Screen-dependent cursors : : : : : : : : : : : : : : : : : : : : : : : 88 7.8.1 Obtaining handles from the oracle : : : : : : : : : : : : : : : 88 7.8.2 The handle object : : : : : : : : : : : : : : : : : : : : : : : 89 7.9 Screen-dependent pixmaps: : : : : : : : : : : : : : : : : : : : : : : 90 7.9.1 Obtaining handles from the oracle : : : : : : : : : : : : : : : 90 7.9.2 The handle object : : : : : : : : : : : : : : : : : : : : : : : 91 7.9.3 The raw representation: : : : : : : : : : : : : : : : : : : : : 91 7.10 Screen-dependent fonts: : : : : : : : : : : : : : : : : : : : : : : : : 94 7.10.1 Obtaining handles from the oracle : : : : : : : : : : : : : : : 94 7.10.2 Font attributes : : : : : : : : : : : : : : : : : : : : : : : : : 95 7.10.3 Registering fonts: : : : : : : : : : : : : : : : : : : : : : : : 97 7.10.4 The handle object : : : : : : : : : : : : : : : : : : : : : : : 97 7.10.5 The raw representation: : : : : : : : : : : : : : : : : : : : : 98 7.11 Color maps : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 100 7.11.1 Obtaining handles from the oracle : : : : : : : : : : : : : : : 100 7.11.2 The handle object : : : : : : : : : : : : : : : : : : : : : : : 101
8 Geometry interfaces 104
8.1 The Axis Interface : : : : : : : : : : : : : : : : : : : : : : : : : : : 104 8.2 The Point interface : : : : : : : : : : : : : : : : : : : : : : : : : : : 104 8.3 The Interval interface : : : : : : : : : : : : : : : : : : : : : : : : : 105 8.4 The Rect interface : : : : : : : : : : : : : : : : : : : : : : : : : : : 107 8.5 The Region interface : : : : : : : : : : : : : : : : : : : : : : : : : : 110 8.6 The Path interface : : : : : : : : : : : : : : : : : : : : : : : : : : : 113 8.7 The Trapezoid interface : : : : : : : : : : : : : : : : : : : : : : : : 116
9 Implementing your own splits 117
9.1 The VBTClass interface : : : : : : : : : : : : : : : : : : : : : : : : 117 9.1.1 Specifications of the split methods : : : : : : : : : : : : : : : 122 9.1.2 Specifications of the up methods : : : : : : : : : : : : : : : : 124 9.1.3 Getting and setting the state of a VBT : : : : : : : : : : : : : 125 9.1.4 Procedures for activating the down methods of a VBT: : : : : 126 9.1.5 Procedures for activating the up methods of a VBT : : : : : : 128 9.2 The FilterClass interface : : : : : : : : : : : : : : : : : : : : : : : : 129 9.3 The ProperSplit interface: : : : : : : : : : : : : : : : : : : : : : : : 130
10 Implementing your own painting procedures 132
10.1 The Batch interface : : : : : : : : : : : : : : : : : : : : : : : : : : 132 10.2 The BatchUtil interface : : : : : : : : : : : : : : : : : : : : : : : : 132 10.3 The PaintPrivate interface : : : : : : : : : : : : : : : : : : : : : : : 134
iii
11 Miscellaneous interfaces 139 11.1 The VBTTuning interface : : : : : : : : : : : : : : : : : : : : : : : 139 11.2 The TrestleComm interface : : : : : : : : : : : : : : : : : : : : : : 139
12 History and Acknowledgments 140
References 141
Index 143
iv
