A Practical Guide To X Window Programming :

Developing Applications with the XT Intrinsics

and OSF/Motif First Edition Keller pdf download

https://textbookfull.com/product/a-practical-guide-to-x-window-
programming-developing-applications-with-the-xt-intrinsics-and-
osf-motif-first-edition-keller/

Download more ebook instantly today - get yours now at textbookfull.com

We believe these products will be a great fit for you. Click
the link to download now, or visit textbookfull.com
to discover even more!

How to Build Android Apps with Kotlin A practical guide

to developing testing and publishing your first Android
apps 2nd Edition Alex Forrester

https://textbookfull.com/product/how-to-build-android-apps-with-
kotlin-a-practical-guide-to-developing-testing-and-publishing-
your-first-android-apps-2nd-edition-alex-forrester/

Efficient R Programming A Practical Guide to Smarter

Programming 1st Edition Colin Gillespie

https://textbookfull.com/product/efficient-r-programming-a-
practical-guide-to-smarter-programming-1st-edition-colin-
gillespie/

Programming Excel with VBA A Practical Real World Guide

Flavio Morgado

https://textbookfull.com/product/programming-excel-with-vba-a-
practical-real-world-guide-flavio-morgado/

Window seat on the world my travels with the Secretary

of State First Edition Johnson

https://textbookfull.com/product/window-seat-on-the-world-my-
travels-with-the-secretary-of-state-first-edition-johnson/
Programming Kubernetes Developing Cloud Native
Applications 1st Edition Michael Hausenblas

https://textbookfull.com/product/programming-kubernetes-
developing-cloud-native-applications-1st-edition-michael-
hausenblas/

SQL Server 2017 Developer s Guide a professional guide

to designing and developing enterprise database
applications 1st Edition Dejan Sarka

https://textbookfull.com/product/sql-server-2017-developer-s-
guide-a-professional-guide-to-designing-and-developing-
enterprise-database-applications-1st-edition-dejan-sarka/

The Trouble with Maths A Practical Guide to Helping

Learners with Numeracy Difficulties 4th Edition Steve
Chinn

https://textbookfull.com/product/the-trouble-with-maths-a-
practical-guide-to-helping-learners-with-numeracy-
difficulties-4th-edition-steve-chinn/

Reservoir modelling: a practical guide First Edition

Cannon

https://textbookfull.com/product/reservoir-modelling-a-practical-
guide-first-edition-cannon/

Arthurian Magic A Practical Guide to the Wisdom of

Camelot First Edition John & Caitlin Mathews

https://textbookfull.com/product/arthurian-magic-a-practical-
guide-to-the-wisdom-of-camelot-first-edition-john-caitlin-
mathews/
 A Practical Guide to
X Window
Programming
Developing Applications with the Xt Intrinsics
and OSF/Motif™
 A Practical Guide to
X Window
Programming
Developing Applications with the Xt Intrinsics
andOSF/MotiFM

Brian J. Keller

CRC Press
Boca Raton Ann Arbor Boston
First published 1990 by CRC Press
Taylor & Francis Group
6000 Broken Sound Parkway NW, Suite 300
Boca Raton, FL 33487-2742

Reissued 2018 by CRC Press

© 1990 by Multiscience Press, Inc.

CRC Press is an imprint of Taylor & Francis Group, an Informa business

No claim to original U.S. Government works

This book contains information obtained from authentic and highly regarded sources. Reasonable efforts have
been made to publish reliable data and information, but the author and publisher cannot assume responsibility for
the validity of all materials or the consequences of their use. The authors and publishers have attempted to trace the
copyright holders of all material reproduced in this publication and apologize to copyright holders if permission to
publish in this form has not been obtained. If any copyright material has not been acknowledged please write and
let us know so we may rectify in any future reprint.

Except as permitted under U.S. Copyright Law, no part of this book may be reprinted, reproduced, transmitted, or
utilized in any form by any electronic, mechanical, or other means, now known or hereafter invented, including
photocopying, microfilming, and recording, or in any information storage or retrieval system, without written
permission from the publishers.

Trademark Notice: Product or corporate names may be trademarks or registered trademarks, and are used only for
identification and explanation without intent to infringe.

Library of Congress Cataloging-in-Publication Data

A Library of Congress record exists under LC control number: 90081308

Publisher’s Note
The publisher has gone to great lengths to ensure the quality of this reprint but points out that some imperfections
in the original copies may be apparent.

Disclaimer
The publisher has made every effort to trace copyright holders and welcomes correspondence from those they
have been unable to contact.

ISBN 13: 978-1-315-89030-2 (hbk)

ISBN 13: 978-1-351-06940-3 (ebk)

Visit the Taylor & Francis Web site at http://www.taylorandfrancis.com and the
CRC Press Web site at http://www.crcpress.com
 Once in a lifetime a person comes along
and really makes a difference in another person's life.
This book is dedicated to the person who made
that difference in mine.

To Kim
 Contents

Preface xi

Acknowledgments xiii

Introduction 1
1.1. A Brief History of X 1
1.2. The X Window System Architecture 2
1.3. The X Programming Interface — Xlib 6
1.4. Reasons for Using Xt Over Xlib 7
1.5. Why a Practical Guide? 7

Fundamentals: A Helpful Review for Understanding Xt 9

2.1. Review of Structures and Pointers 9
2.2. Window System Basics 13
2.3. Event-Driven Programming 15
2.4. Object-Oriented Programming 16

Xt Basics: An Introduction to Xt-based Widgets 19

3.1. What Is a Widget, Really? 19
3.2. Classes of Widgets 20
3.3. The Components of a Widget 21
3.4. A Windowless Object: The OSF/Motif Gadget 23

Basic X Graphics: Text, Fonts, Bitmaps, and Colors 25

4.1. Text and X 25
4.2. Graphics Context 26
4.3. Handling GCs 27
4.4. Multi-Font Text 28
4.5. Fonts 28
4.6. Bitmaps for Icons 31
4.7. Foreground and Background 32
viii A Practical Guide to X Window Programming

5 Building Applications: Developing with Xt 33

5.1. Conventions 33
5.2. Application Structure 34
5.3. Providing Application Resources 42
5.4. Handling Events 52

6 Building Widgets: Primitive Widgets 99

6.1. Structure of a Primitive Widget 99
6.2. Inheritance in Xt 105
6.3. Requirements for the FieldEdWidget 106
6.4. Constructing the Widget 107
6.5. Summing Up 139

7 Building Widgets: Container Widgets 141

7.1. Composite Widget 141
7.2. Structure of a Composite Widget 141
7.3. Structure of a Constraint Widget 144
7.4. Summing Up 145

8 Sample Application: A Character-Oriented Client 147

8.1. Designing an Xt Application 147
8.2. Standardizing the Interface 148
8.3. Selecting From the Widget Sets 150
8.4. Building the Application 153
8.5. Summing Up 179

9 A Look at OSF/Motif 181

9.1 Motif Environment 181
9.2 Motif Window Manager 182
9.3 The Motif Widgets 187
9.4. Sample Motif Clients 194

10 A Sample Application: Motif Version 209

10.1. Client Components 209
10.2. Building the Client 209
10.3. Summing Up 232

11 Application Development: Advanced Topics 233

11.1. Inter-Client Communication 233
11.2. Using Multiple Displays 248
11.3. Summing Up 253
 Contents ix

Appendix A
Widgets, Classing, and Exported Functions
OSF/Motif and Athena XAW (R4 and R3) 255
A.I. Motif Widgets 255
A.2. Motif Widget Classing 256
A.3. Motif Exported Functions 261
A.4. XAW R4 Widgets 265
A.5. XAW (R4) Classing 266
A..6 XAW R4 Exported Functions 270
A.7. XAW R3 Widgets 271
A.8. XAW R3 Classing 271
A.9. XAW R3 Exported Functions 273

Appendix B
Quick Xt Reference Guide XI1R4 275
B.l.Typedefs 275
B.2. BASE Widget Typedefs 276
B.3. Translation Management Typedefs 276
B.4. Intrinsic Specific Procedure Typedefs 276
B.5. Container Routines 283
B.6. Resource Conversion 284
B.7. Event Handling 284
B.8. Checking Routines 285
B.9. Selection Management 286
B.10. Geometry Management 286
B. 11. Translation Management 288
B.I2. Keycode and Keysym Procedures 290
B.13. Event Management 292
B. 14. Event Gathering Routines 294
B.15. Logic Macros 296
B.16. Widget State 296
B.17. Argument List 297
B.18. Information Gathering Routines 298
B. 19. Widget Mapping 299
B.20. Callbacks 299
B.21. Geometry Management 300
B.22. Pop-ups 300
B.23. Widget Creation 302
B.24. Toolkit Initialization 303
B.25. Error Handling 308
B.26. Memory Management 311
x A Practical Guide to X Window Programming

B.27. Work Procedures 312

B.28. Graphics Context 312
B.29. Selection Mechanisms 313
B.30. Grabs 315
B.31. Miscellaneous 317

Appendix C
Quick Guide to the OSF/Motif Widget Set 319
C.l.OSF Widgets 319
C.2. Convenience Routines 320
C.3. XmTextWidget Public Routines 321
C.4. Resource Values 325
C.5. Motif Callback Data Structures 327

Bibliography 339

Index 341
 Preface

Application development is the art of filling erratic requests for unusual system
requirements in a "need it yesterday" mode from end users. Many who "... choose
to accept this mission" are confronted with rapid technological changes that must
be kept up with (if not for technological curiosity, then simply because "that's the
way to go"). For many, the X Window System has become "the way to go."
When X was first introduced, the documentation was limited to manuals and
"overview" documents. For those of us who started with X early on these were a
blessing, but learning how to create X clients was not easy or straightforward. There
were few examples and hardly any books that could explain the details of X
Window programming. This lack of a text spawned the idea to create a book that
would cover the details, with sufficient practical examples so that the army of
application writers who wanted to develop applications could do so without too
much pain.
To start, this book is not an Xlib book. Xlib is much too low-level for application
writers. Instead, this book addresses the layer of development referred to as the Xt
Intrinsics. This is a higher level of interaction with the X Window System than
Xlib. It is based on a notion called object-oriented programming, and can greatly
increase your productivity as you develop X Window clients. This book is a
practical guide to Xt, and can be used as a source for application examples. It covers
topics that are useful to the many application programmers who need education in
developing with the Intrinsics.
The audience for this book is anyone who wants to develop Xt-based X Window
clients. It is written with the end-user application writer in mind, so the style is
straightforward and direct. No complicated, technically confusing, "beat around
the bush" verbage! The assumption is that the reader is not creating four-
dimensional cyberspace artifical-reality applications. Instead, the reader develops
applications that are based on end-user requests (those erratic "need it yesterday"
specifications). These people have little time to discuss "byte splitting" or the
challenges involved in piping instructions to UNIX utilities. They need answers
now.

XI
xii A Practical Guide to X Window Programming

As a practical guide, this book continually builds on knowledge as it is acquired.

Chapter 1 begins with the history of X, so that you have an idea where it all started.
Chapter 2 is a fundamentals section that covers some important points in the C
language that you need to be comfortable with before starting Xt programming.
This chapter also includes Window System basics, event-driven programming, and
object-oriented programming concepts.
Chapter 3 is a basic introduction to Xt and the notion of widgets. Chapter 4
discusses several Xlib details that Xt application writers should be aware of,
including graphic contexts, font handling and naming, color allocation, and textual
display. Chapter 5 is the core part of the book. It uses several examples to discuss
all of the major components of the Xt Intrinsics (resource gathering, command-line
parsing, event handling, translations, etc.).
Chapter 6 is a detailed look at primitive widgets. This is accomplished through
the construction of a useful "field editor" widget. This widget is integrated into a
character-oriented application later in the book.
Chapter 7 is a basic overview of container widgets.
Chapter 8 looks into the details of designing Xt applications. It demonstrates the
use of several widgets for constructing interface components including pop-up
menus, pop-up option lists, command buttons, entry fields (using the widget from
Chapter 6), and help facilities. There are also sections that cover keyboard traversal
and ways to streamline development.
Chapter 9 introduces the commercial application environment called Motif
provided by the Open Software Foundation (OSF). The chapter explores, at a high
level, the various widgets and how to work with or customize the Motif Window
Manager (mwm). Some clients are developed to demonstrate the use of the Motif
widgets, including a client that demonstrates the mixing of widget sets (Athena and
Motif).
Chapter 10 shows how to port the application developed in Chapter 8, making
it a Motif-compliant application. This chapter demonstrates pop-up help, pull-
down menus, push buttons, text widget, field editing, keyboard traversal, and two
kinds of help mechanisms.
Finally, Chapter 11 discusses some of the advanced topics in the Intrinsics.
These topics include interclient communication, selection mechanisms in Xt, and
controlling multiple displays with the same client.
Technical books for the most part are not much fun. The style is often esoteric,
dry, and sometimes boring. From the beginning, I intended this project to be
different. I think the reader should enjoy the time spent reading. After all, you're
taking the time out of a busy schedule to read this book. Why not enjoy yourself
and learn at the same time? If I've done my job right, you'll have a few laughs and
learn quite a bit.
 Acknowledgments

As we go through life, we seldom get a chance to publicly acknowledge those who

have had some influence on what we do. This book could not have been possible
if it weren't for a few individuals whose actions in one way or another made the
dream of writing into a reality.
Vincent G. Alonzi has been a friend and colleague for quite some time. As a
friend, he has made many a day very entertaining (/ believe you still owe me two
dozen bagels?), and as a colleague, every new job an adventure (Who could forget
Trevose, PAT). It was his "Psst, gotta job for you a t . . . " that triggered the idea for
this book. His thoughtful review and suggestions have greatly helped me in this
effort. (Can you actually believe it's done?)
Bennie Larrier has helped me in ways neither he nor I can understand. I don't
know many who would put themselves on the line to get someone an opportunity
like he did for me.
Paul Kavanaugh acted as the "network node" that brought this book to a real
publisher. His "It's good . . . . A bit too folksy for a Brit" made me realize that I
actually did hit the mark.
Alan Rose is the man behind the scenes. He gave me a chance, bought me some
lunch, got me the loaned computer, and gave me all the time I needed. Alan, thanks!
Hal Remish made the IBM PS/2 Model 70 (the development platform for all
clients in this book) available. I'm sure when he gave it to me he thought it would
be back shortly. Thanks, Hal, for understanding the delays.
Thanks to all the folks who had anything to do with creating and maintaining
the X Window System. If it weren't for their hard work and dedication to bringing
their dreams to realities, mine would not exist. The world needs more of you.
Lastly, Kimberly A. Lanning provided me with my inspiration. From the day I
met her I knew she was someone special. Her patience and understanding during
this long process has made me realize just how special she really is, and how lucky
I am to have her in my life. Thanks, Honey. I love you.

Brian J. Keller

XIII
 1

Introduction

This chapter provides you with a brief history of the X Window System (also called
just X), its architecture, a discussion of Xlib, and reasons why Xt is better suited
than Xlib for most application development.

1.1. A Brief History of X

X started as a research project driven by the need to create a hardware-independent
display mechanism for Project Athena. Project Athena is a major research project
being conducted at the Massachusetts Institute of Technology (MIT) to advance
the state of technology for distributed systems. This project is heavily financed by
International Business Machines (IBM) and the Digital Equipment Corporation
(DEC).
The original system was designed by Robert Scheifler, Ron Newman, and Jim
Getty. It borrowed some design ideas from a window system created at Stanford
University called W. The current release, XI1, has been worked on by thousands,
and is still being improved as we all start to use it.
X was developed to provide a distributed mechanism to run applications (re-
ferred to as clients') across a network on a variety of hardware platforms. The
developers focused on providing highly portable code, so that the system could be
implemented on micros (IBM PCs), minis (MicroVaxes), workstations (IBM Rise
System 6000, Sun Spare), and supercomputers (Cray). The system had to be able
to run under several operating environments and provide high performance. And,
in keeping with open systems concepts, X had to be free from user interface policy.
The ability of X to run on and across different platforms makes it perhaps one
of the most innovative technologies to be developed in computing in recent years.
And for this very reason, major vendors (IBM, AT&T, DEC, HP, and Sun) have
embraced X as their display standard for advanced workstations.

1
2 A Practical Guide to X Window Programming

1.2. The X Window System Architecture

1.2.1. Client-Server

The X architecture is based on a client-server relationship. The server (called the

X server) is responsible for the display. A display is considered an X station (a
computer that runs the X server) with one or more CRT, keyboard, and mouse (or
other pointing device). A single instance of an X server is called a display;
therefore, a display (CRT) may have multiple displays by running multiple X
servers, as shown in Figure 1-1.

IBM PS/2 Model 70 Cray

Data Collection Analytical
Client Client

Xlib Xlib
Server Queue Server Queue

IBMRS/6000320

Portfolio
Pricing
Client X
Server
Xlib
Server Queue

Keyboard =—' CRT/Display Input Device

Figure 1-1 Client-server model.

 Introduction 3

X is a network windowing system that allows a client to run on either the server
host or any other host on the network. The server sends and receives display
information (i.e., screen-writing commands, keyboard hits, or mouse movements).
This capability implies that a single display station could have numerous clients
from all over the network sending messages to it. An IBM PS/2 could have a client
running on a Cray, another running on an IBM Rise System 6000, and still another
locally. This is truly a distributed processing capability.

1.2.2. X Server Responsibilities

The server is responsible for five tasks:

1. Providing multi-client access.

2. Receiving and understanding client messages.
3. Sending user responses in the form of messages to the clients.
4. Performing all drawing.
5. Storing and maintaining data structures for limited resources (color maps,
cursors, fonts, and graphic information known as "graphics context").

As we mentioned before, the X server can handle client requests over a network.
This provides for the distributed nature of network computing. It is now feasible
to connect several processor classes in your network to handle specific applications.
What this really means is that additional computing power can be added incremen-
tally, allowing for a more controlled increase in a site's computing power.
When clients make requests to the server, the server must be able to decipher
what is being requested. The X server acts like a dispatcher directing traffic in a
city, who receives a request and must determine what the request is for. Based on
the requirements of the request, he must decide which type of vehicle to use: a cab,
a van, or a bus? The X server acts in a similar fashion. It must figure out what
drawing or action it should take based on the request received, and then take action
accordingly.
One of the primary tasks that the X server provides is the control of input and
output functions. Whenever a key is pressed, the server must determine which client
should be informed of it, if any. Similarly, when the mouse is moved the server
must inform one or more clients.
As a way of improving performance, the X server has the responsibility of
performing all drawing that the clients request. So, when a client intends to draw
a line or a character of text, it makes a request to the server, and the server performs
all the necessary steps for generating the graphics. This greatly improves perform-
ance since the client need not be concerned about the "how" of drawing. Addition-
ally, the X server maintains the resources required for generating the graphics.
Fonts, colors, window coordinates, and other graphical pieces of information
are the kinds of resources stored by the server. These data items are given
identification codes by the server so that clients may refer to them. This makes
4 A Practical Guide to X Window Programming

more sense than sending an entire graphics structure with large amounts of
information over a network. By doing it this way, X reduces the network traffic
and leaves bandwidth for other messages.

1.2.3. Window Management

X was developed as a generic mechanism for providing display capabilities in a

network environment. MIT did not enforce a particular style for user presentation;
rather, they provided a way of creating such display policies. One inclusion that is
different from other window systems is the separation of window management (i.e.,
moving, iconifying, resizing) from the client.
The window manager is the "ruler" of the screen (see Figure 1-2). It is respon-
sible for informing its windows about policy. The X Window System does not
commit to any particular window manager. It was felt that the vendors who
supported X would provide their own. This is demonstrated by the inclusion of a
window manager for OSF/Motif as well as AT&T XWIN (Open Look) interface
kits.

Root Window

Window Manager

! i

Client

Client

Figure 1-2 Window manager in X.

 Introduction 5

The window manager has the right to enforce anything it wants with respect to
screen layout, overriding any and all client requests for space. It might elect to
move windows to make room for others, or it might inform the client that it can
only be a fraction of the size requested.
The notion that a requested window size may not be granted is significant to
application writers. Take great care in designing applications so as to eliminate any
dependency on a particular window manager's style. Your applications must be
able to cooperate with any window manager, and also without one. Noting this
early will save you a lot of time in the future.

1.2.4. X Protocol

I stated earlier that X has its own protocol, /^protocol is nothing more than an
agreed-upon form of communication. In the X world, this is accomplished via
network packets (chunks of information). There are four kinds of packets that exist
in X: events, replies, requests, and errors.
Events are things like a keyboard press, a mouse movement, or a screen update.
Just like in the real world, events can happen at any time. Clients must be ready
and able to cope with this. The client will never be able to know for sure if it has
to respond to a keystroke or to repaint itself. In order to accommodate this, the
client must inform the server of the events it cares about, and then provide
processing for when the event is reported. (This is discussed in greater detail in a
later section of this book.)
Requests are generated by a library function (Xlib) and sent to the server. A
request packet might contain drawing information, or perhaps a question about a
specific window. When the request is for locally stored information, it quite
obviously does not have to go through the server. Otherwise, the request is passed
to the server where it is acted on and a reply is sent.
Replies emanate from the server to Xlib only when a previous Xlib request was
for server-based information. This situation is considered a round-trip, and as might
be inferred, is quite costly. After all, the client pays the price for the request and
must also pay for the reply. Considering the network framework, this could be quite
substantial if the client makes many requests.
Errors are also sent by the server to Xlib. Xlib has two kinds of error-handlers:
recoverable and fatal. The error is not sent to the client until the client-server
connection is flushed (typically when an event is read). The reason for this latency
in error reporting is due to a design consideration. Since X is network based, and
it is more efficient to send chunks of data across a network, the designers chose to
have the server queue up events and errors while the client queues up requests. The
server gives the server queue to the client when the client initiates the transaction.
At that time the client gives the server its queue.
6 A Practical Guide to X Window Programming

1.3. The X Programming Interface — Xlib

All clients eventually will use Xlib. This is true if you write using straight Xlib or
a higher level library like Xt. As stated earlier, Xlib translates the request into a
network packet to be sent to the server.
As shown in Figure 1-3, Xlib is the lowest level that an application writer can
use for creating X-based clients. The functions that make up Xlib perform every-
thing that any client could possibly need. This includes things such as opening and
closing the display, getting a particular font or color, drawing a line, drawing text,
creating and destroying a window, getting user defaults, and parsing the command
line.
The library is rich with functions and is currently being expanded to include
extensions for 3-D drawing as well as Display PostScript. In any event, the
technique for creating an X-based client is the same in all cases, and the process
can be rather lengthy.

APPLICATION
CODE

Other Tools

Toolkit
Xt Intrinsics
Xlib
X Protocol
Operating System
Figure 1-3 X programming layers.
 Introduction 7

1.4. Reasons for Using Xt Over Xlib

As any developer knows, a set of routines that perform the same task and are
gathered into a library is invaluable. After all, who wants to write the same tired
code all the time? If you were an Xlib developer, you would have to rewrite
window-creation and resource-gathering routines for every client. Also, event-han-
dling is not as intuitive in Xlib as it is in Xt. Lastly, the number of lines of code in
an Xt client can be far less than the same one written using Xlib.
When X was first introduced, a basic toolkit was provided. It was a collection
of routines that created display elements like scroll bars, command buttons, and
text editing mechanisms. The writer simply had to invoke these convenience
routines to create a window and add the functionality for a scroll bar. At this level,
an application writer would find it easier to develop interfaces, and this would be
the level most application writers prefer.
When the protocol changed from X10 to XI1, the developers of X took the
opportunity to re-create the toolkit. They did this by providing an objective
approach to building interface components. This included the Intrinsics as mecha-
nisms for using interface components and Athena widgets as samples of how to
write them.
Xt is not a set of widgets, rather it is a style of programming. It defines how a
widget must be written and how applications must use them, but it does not in itself
provide a particular widget set. The Athena widget set (Xaw) has been provided as
a model for application writers to get a feel for developing with and creating new
widgets. Most vendors provide these widgets as samples, and for that reason they
are used in many of the examples found in this book.
So why bother with widgets if you can create clients with Xlib? The reason is
quite simple: widgets are easy to use (if documented correctly), and can eliminate
many redundant steps that all X clients must perform. Also, Xt-based clients are
easier to write, especially when the interface becomes complex. Lastly, the code
savings is tremendous. This is due to the objective mechanisms that Xt employs
(you'll see why as you read on).

1.5. Why a Practical Guide?

Anyone who has attempted to write applications without samples is a true pioneer,
and deserves a tip of the cap. For the rest of us, an example goes a long way in
aiding understanding. Most everyone I have ever developed with found that source
code was the key to their success as developers. I must point out, though, that while
having examples is great, they are simply a possible solution, not the only one. You
are encouraged to use the techniques in this book, but you should also search for
new and perhaps more efficient ways of doing things.
This book demonstrates the majority of topics that application writers need to
address when they begin to write their own interfaces. Sure, you could do what I
8 A Practical Guide to X Window Programming

did to learn Xt. You would spend a lot of hours reading the pages of the Xt Intrinsics
code along with the source from the widget sets (Athena and HP). You would
attempt to use the MIT documents and search for examples over the network. You
would go to lunch with one of the creators of the XI1 Xt Intrinsics (Joel Mc-
Cormack) and discuss the philosophy of the design of Xt. Finally, you would attend
the X Technical Conference, purchase some Xlib books, and start to bang out code.
In the end, you would finally be clear on how to write Xt-based clients.
I would recommend you save yourself some time and use this book. Believe me,
you will get more out of this book than you realize. Enjoy!
 Fundamentals: A Helpful
Review for Understanding Xt

In order to get a foundation from which to build a better understanding of Xt, it is

important to discuss a few concepts prior to diving in. This chapter is intended to
get everyone on the same playing field.

2.1. Review of Structures and Pointers

If you haven't figured it out yet, let me tell you: C is the language used to program
with Xt. For many an application programer this might cause a wince. After all, C
can be a bit of a pain to deal with. It gives great flexibility to get at the low levels
of the machine, but with that comes the ability to crash the system. (Has anybody
ever crashed a system with a C program? Let's see a show of hands.)
Perhaps the most problematic part of the C language for many are these things
called pointers. So, in an attempt to set you straight, let's discuss them for a bit.
A pointer is variable in the C language. Its sole purpose in life is to look at a
place in the computer's memory. The thing a pointer holds is called an address. An
address is simply a place in the computer's memory. You'll find the operating
system, data, and programs loaded there.
In C there are a variety of data types. The usual are int (short and long), float,
double, and char. Each of these can have an associated pointer type: int*, float*,
double*, char*. For example, if you saw the following definition in a C program:

int x, *xp;

it would read "x is of type int and xp is of type pointer-to-int." This means that xp
can contain the memory address of another variable that is of type int. The same
holds true for float, double, and char.
To get a pointer to point at something, you must assign it the thing's memory
address (see Figure 2-1). Recalling the earlier definition, you could have xp point
to x by doing the following:
9
10 A Practical Guide to X Window Programming

Pointer-to-Value
int ival,*ip;
ival = 12;
ip = &ival;

ip * ival
0x2000 storage location 0x1000

0x1 000 value at location 12

Pointer-to-Pointer-to-Value
char cv,*cp1 ,*cp2;
cv = 'A';
cp1 = &cv;
cp1 = cp2; /* pointers are already addresses */

cp2 E cp1 E cv
0x2018 storage location 0x2016 0x2010
0x2016 value at location 0x2010 A
Figure 2-1 Pointer.

xp - &x;

This reads "assign the address of x to xp." Since xp is a pointer type, xp now looks
atx.
Suppose you wanted to get the value that a pointer was looking at. How could
you do that? It is pretty simple, actually. The C language provides the asterisk "*"
as an operator for getting the value (not to be confused with multiplication or the
definition of the pointer).
For example, suppose the code looked like the following:

int x = 2,*xp;
int q;
xp = &x;

and you wanted to assign the value in x to q. It would be easy to assign the value
of x to q by simply saying
 Fundamentals: A Helpful Review for Understanding Xt 11

x;

but you are using pointers and would rather see how to do this using them.
Therefore, to assign the value of x to q using the pointer xp, you write the following:

q = *XP;

This says "assign the value that xp is pointing at to q," so now q has the value 2.
This really isn't so bad. Now that you think you feel good about pointers, just
remember:
A Pointer is like 220 volts of electricity. If you don't ground it well, you could
lose your life!
That is, pointers are fantastic when used with care, and very dangerous when
they are not. Since they truly are memory addresses, you could be pointing to an
area that is in the data space of another program — or anywhere else, for that matter.
If you're not careful, eventually things will break and you'll either get that useful
message, "Segmentation violation" (the OS cop is out to get you), or worse, your
machine will start to reboot itself (the old pointer gremlin is at it again).
Now that you understand pointers better, let's look at another useful tool in C's
arsenal: the structure. Just like the name implies, a structure gives you a way of
placing data in a nice, neat, orderly manner.
If you have ever done database programming, you've come across structures
when you defined records for the database. As an example, suppose you are
interested in defining a structure for a trade (exchange of stocks or bonds) record.
You know that the members would include security, trader id, buy/sell flag,
quantity, and price. In C, this could look like the following:

struct {
char *security;
char *traderld;
char buy_or_sell;
int quantity;
float price;
} tradeRecord;

Another powerful feature of the C language is its ability to create new data types.
This is accomplished using a typedef statement. Essentially, you can create a
shorthand notation for a new storage class of your own. By far the most common
use of the typedef statement is with a structure. For example, if you wanted to use
the tradeRecord in other places in your program, you could create a typedef like
this:
12 A Practical Guide to X Window Programming

typedef struct _TradeRecord {

char *security;
char *traderld;
char buy_or_sell;
int quantity;
float price;
} TradeRecord;

You now have a new type called TradeRecord. With the new TradeRecord type
you can go about defining some structures in your program.

TradeRecord Equity =
{"IBM","BJK",'B',1000,100.25};

TradeRecord *PtrToIt;
PtrToIt - SEquity;

Now let's access some of the members:

printf("%s %c %d shares of %s at $ %f\n",

Equity.trader,Equity.buy_or_sell,
Equity.quantity, Equity.security,Equity.price);

This would print the following:

BJK B 1000 shares of IBM at $ 100.25

Notice that you used the "." (dot) operator to access the members. This is the way
C gets to the members of structures when the structure variable is not a pointer
type. Now let's use the pointer type PtrToIt to get the values:

printf("%s %c %d shares of Is at $ %f\n",

PtrToIt->trader,PtrToIt->buy_or_sell,
PtrToIt->quantity, PtrToIt->security,PtrToIt->price);

This would print the following:

BJK B 1000 shares of IBM at $ 100.25

Notice that you used the "->" (arrow) operator to access the members. This is the
way C gets to the members of structures when the structure variable is a pointer
type.
Since you are by now an expert at this, let's cover one last detail that is used
heavily in Xt. This is the opaque pointer type. The opaque pointer type used in the
Xt is "caddrj" (changed to XtPointer in X11R4) and is defined as either "char *"
or "void *" depending on the C compiler being used. The opaque pointer is allowed
 Fundamentals: A Helpful Review for Understanding Xt 13

to assume the role of a pointer to int, pointer to float, or pointer to whatever, as in

the following code fragment:

caddr_t chameleon;
int x - 2;
chameleon • &X)
printf("%d\n",'chameleon);

If this brief review of pointers and structures isn't enough, refer to one of the
zillion books written on the C language. Or use the "default" book by Kerninghan
and Richie (the second edition is quite good).

2.2. Window System Basics

In order to write applications for X, you should get a feel for some of the basic
relationships that exist. X is built using a hierarchical window system termed a
window tree. There will always be one root window. The root window always
covers the entire display area, and all other windows are its descendants. Addition-
ally, windows on the same level in the tree are called siblings while the parent of
a child is called an ancestor to the child. This is shown in Figure 2-2.

Root Window <o

Window A <p> Window C

2 , (P>
p
Window B < >
Window A1 Window C1
2

Window B1 Window B2

1. Child Relationship
2. Sibling
(P) Parent Relationship

Figure 2-2 Parent/child/sibling.

14 A Practical Guide to X Window Programming

An X window can be viewed as a "roundtangle" — usually, but not quite always,

a rectangle. The reason for the new name is that for most of X's life all that
programmers could get were rectangles. However, with XI1R4, the folks at MIT
incorporated a "shapes" extension, so windows need not be rectangular.
The upper-left corner of an X window is considered to be its origin (see Figure
2-3). The x-axis increases as you go left while the y-axis increases as you go down.
All coordinates in X are relative, that is, from the window's point of view all things
start at 0,0. If a window is created and is offset from the root window at 100,100
the root window's perspective of the child's origin is 100,100 while the child views
it as 0,0.
The X server is where all windows live. Whenever a window is created, the
application must ask the X server to do it. The server adds the newly created
window to the window tree when the request is made. Once added, the client may
request to be mapped and hence viewable by the user.
There are times when windows are mapped yet are not viewable. These situa-
tions occur for three reasons:

1. One of the ancestors is not mapped.

2. One window completely obscures another (as in window C of Figure 2-4).
3. When an ancestor completely clips a window.

+y +y

/offset

x offset
height

width

Figure 2-3 Window geometry.

Other documents randomly have
different content
 THE CHKISTTAN. FRIENDSHIP. L. M. A. MESSINGER. I. Je -
sus, thou joy A-1 of lov - ing hearts, Thou Fount of life, thou Light of
men, ^ I — #:i 1 fjT 1 1 From the best bliss that earth im-parts, We
turn un - filled to thee ^ h 1 :t=: QQQ BERNARD OF CI.AIRVEAUX.
I091-I153. 00*J Tr. by RAY PALMER. 1858. 1 Jesus, thou joy of
loving hearts, Thou Fount of life, thou Light of men, From the best
bliss that earth imparts. We turn unfilled to thee again. 2 We taste
thee, O thou living bread! And long to feast upon thee still ; We
drink of thee, the fountain-head. And thirst our souls from thee to
fill. 3 Our restless spirits yearn for thee, Where'er our changeful lot
is cast ; Glad when thy gracious smile we see, Blest when our faith
can hold thee fast. 4 O Jesus, ever with us stay ; Make all our
moments calm and bright ; Chase the dark night of sin away; Shed
o'er the world thy holy light. AMES. L. M. 340 JAMES EDMESTON.
1844. 1 Fountain of grace, rich, full, and free, What need I that is
not in thee ? Full pardon, strength to meet the day, And peace which
none can take away. 2 Doth sickness fill the heart with fear ? 'Tis
sweet to know that thou art near. Am I with dread of justice tried?
'Tis sweet to feel that Christ hath died. 3 In life, thy promises of aid
Forbid my heart to be afraid ; In death, peace gently vails the eyes;
Christ rose, and I shall surely rise. 4 O all-sufiicient Saviour! be This
all-sufiiciency to me ; Nor pain nor sin nor death can harm The
weakest shielded by thine arm. SIGISMUND NEUKOMM. 1778-1858.
S — ^ — ^3 I. Fount-ain of grace, rich, full, and » — ^ free. What
need I that is not in thee? 3 I I I -» — i0Full par-don, strength to
meet the day, And peace which none can take a - way. — _^ — ft
..^ rtt — 1 — [—
 JOY. ANGELS. L. M. i DR. ORLANDO GIBBONS. 1583-1625.
1. Trem-bling be fore thine aw ful throne, O Lord ! in dust my sins i
1 K ^ Con -tend; O smile and heal the strife 1 Jus - tice and mer - cy
for my life A. L. HILLHOUSE. C8l6. 341 1 Trembling before thine
awful throne, O Lord I in dust my sins I own : J ustice and mercy for
my life Contend ; O smile and heal the strife ! 2 The Saviour smiles !
upon my soul New tides of hope tumultuous roll ; His voice
proclaims my pardon found. Seraphic transport wings the sound. 3
Earth has a joy unknown in heaven, The new-born peace of sin
forgiven ! Tears of such pure and deep delight, Ye angels, never
dimmed your sight. 4 Though I amid your choirs shall shine. And all
your knowledge will be mine; Ye on your harps must lean to hear A
secret chord that mine will bear. HAPPY DAY. L. M PHILIP
DODDRIDGE. 1755. 342 1 O, happy day, that fixed my choice On
thee, my Saviour and my God I Well may this glowing heart rejoice.
And tell its raptures all abroad. 2 'Tis done, — the great transaction's
done ; I am my Lord's, and he is mine ; He drew me, and I followed
on. Rejoiced to own the call divine. 3 Now rest, my long-divided
heart, Fixed on this blissful center, rest ; Here have I found a nobler
part, Here heavenly pleasures fill my breast. 4 High heaven that
hears the solemn vow, That vow renewed shall daily hear ; Till in
life's latest hour I bow. And bless in death a bond so dear. E. F.
RIMBAtJLT. 1816-1876. CHORUS.. -I— «J fO, hap-py day, that fixed
my choice On thee, my Sav - iour and my God ! * ( Well may this
glowing heart re-joice. And tell its rapt-ures all a - broad. Hap - py 1
N ±=lt Fine. A — Im day, happy day, When jesus washed my sins
away ! f He taught me how to watch and pray, ) t And live re - joic-
ing ev-ery day ; J /2 . ^ m 177
 NORTHFIELD. C. M. 1 S3 THE CHEISTIAN. J. TNGALLS.
1764-1828. Yea, =3 I. If God is mine, then present things, And
things to come, are mine; Yea, Christ, his word and Christ, his word
and Spirit too, And glo-ry all di-vine, Spirit toOjYea, Christ, his word
and Spir - it too. And glo - ry all di-vine. Yea, Christ, his word and
Spirit too, — If. •■Ay v^iiri:si. Ills wuru
 JOY. DENFIELD. G. G. 1784-1829. i 3 i The glo - ry of my
bright-est days, And com - fort of my nights! ^ !^. ISAAC WATTS.
1707. 345 1 My God, the spring of all my joys, The life of my
delights, The glory of my brightest days, And comfort of my nights!
2 In darkest shades, if he appear. My dawning is begun ; He is my
soul's bright morning star. And he my rising sun. 3 The opening
heavens around me shine With beams of sacred bliss, While Jesus
shows his love is mine, And whispers, I am his. 4 My soul would
leave this heavy clay. At that transporting word, And run with joy the
shining way, To meet my gracious Lord. 346 F. W. FABER. 1849. 1 O
gift of gifts ! O grace of faith ! My God ! how can it be That thou,
who hast discerning love, Shouldst give that gift to me ? 2 How
many hearts thou mightst have had More innocent than mine ! How
many souls more worthy far Of that sweet touch of thine ! IFFLEY.
M. 3 Ah, grace! into unlikeliest hearts It is thy boast to come, The
glory of thy light to find In darkest spots a home. 4 The crowd of
cares, the weightiest cross Seem trifles less than light ; Earth looks
so little and so low When faith shines full and bright. 5 O happy,
happy that I am ! If thou canst be, O faith. The treasure that thou
art in life, What wilt thou be in death? • B. BEDDOME. 1818. 1 O
Lord, if in the book of life My worthless name shall stand, In fairest
characters inscribed By thine unerring hand, — 2 Then I to thee in
sweetest strains. Will grateful anthems raise ; But life's too short, my
powers too weak, To utter half thy praise. 3 Had I ten thousand
thousand tongues, Not one should silent be ; Had I ten thousand
thousand hearts, I'd give them all to thee. DR. G. M. GARRETT.
1872. l.OL ord, if in the b )ok of life, My worl hless name sha 1
stand. In fa irest char-ac-ters inscri ^^f f f TT )ed By thine unerring
h md, — ] 179
 THE CHRISTIAN. CLAXTON. G. M. 3t I. Je - sus, the ver - y
thought of thee, With sweet-ness fills m y breast; r — L b T r r H2 ^
,2 ^ ^ 4^ 1 1 1^0 J O BERNARD OF CLAIRVAUX. USSdttO Tr. by E.
caswall. 1849. 1 Jesus, the very thought of thee, With sweetness fills
my breast : But sweeter far thy face to see. And in thy presence
rest. 2 Nor voice can sing, nor heart can frame, Nor can the memory
find A sweeter sound than Jesus' name, O Saviour of mankind ! 3 O
Hope of every contrite heart ! O Joy of all the meek ! To those who
fall, how kind thou art ! How good, to those who seek ! 4 But what
to those who find? Ah ! this. Nor tongue nor pen can show; The love
of Jesus, what it is. None but his loved ones know. ISAAC WATTS
[719. 349 1 Thou art my portion, O my God; Soon as I know thy
way. My heart makes haste t' obey thy word. And sufiers no delay. 2
I choose the path of heavenly truth, And glory in my choice ; Not all
the riches of the earth Could make me so rejoice. 3 Thy precepts
and thy heavenly grace I set before my eyes ; Thence I derive my
daily strength, And there my comfort lies. 4 NoAV I am thine, forever
thine ; O save thy servant. Lord ; Thou art my shield, my hiding-
place; My hope is in thy word. STEPHENS. C. M. W. JONES. 1726-
1800, S5 I. Thou art my por - tion, O my God ; Soon I know thy
way. My heart makes haste t'o - bey thy word, And suf - fers no de -
lay. 180
 JOY. ST. THOMAS. S. M. G. F. HANDEL. l68$-T759. 1=? 1.
Come, =1= that — love I the I -0Lord, And let -Iyour joys be known
; -«- -tf2.-It Join song of sweet ac cord, -0 — And thus sur I round
the throne. -t351 JOHN KEBLE. 1 Blest are the pure in heart, For
they shall see their God : The secret of the Lord is theirs ; Their soul
is Christ's abode. 2 The Lord, who left the heavens, Our life and
peace to bring, To dwell in lowliness with men, Their pattern and
their King ; 3 Still to the lowly soul He doth himself impart, And for
his dwelling and his throne Chooseth the pure in heart. 4 Lord, we
thy presence seekj May ours this blessing be ; O, give the pure and
lowly heart, A temple meet for thee. ISAAC WATTS. IJOJ. 350 1
Come, ye that love the Lord, And let your joys be known ; Join in a
song of sweet accord. And thus surround the throne. 2 Let those
refuse to sing Who never knew our God ; But children of the
heavenly King May speak their joys abroad. 3 The hill ofZion yields A
thousand sacred sweets, Before we reach the heavenly fields. Or
walk the golden streets. 4 Then let our songs abound. And every
tear be dry ; We're marching through Immanuers ground, To fairer
worlds on high. 1827. BEATITUDE. S. M. Arr. from e. l. white. 1809-
1851. I. Blest are the pure SLffS in heart, -
 THE CHEISTIAIT. ZUNDEL. 8s, 7s. D. \nr. . II JOHN
ZUNDEL. 1815-18 I. Know, my soul, thy full sal - va - tion ; Rise o'er
and fear and care; Fine. Joy to find, in ev - ery sta - tion, Some-
thing still to do or bear : D, s. Think what Je - sus did to win thee :
Child of heaven, canst thou re - pine? n.s. Think what Spir - it dwells
with - in thee ; Think what Fa - ther's smiles are thine; 2 Haste thee
on from grace to glory, Armed by faith, and winged by prayer ;
Heaven's eternal day's before thee ; God's own hand shall guide
thee there : Soon shall close thy earthly mission ; Soon shall pass
thy pilgrim days ; Hope shall change to glad fruition, Faith to sight,
and prayer to praise. HENRY FRANCIS LYTE. 1825. 1 Know, my soul,
thy full salvation ; Rise o'er sin and fear and care ; Joy to find, in
every station. Something still to do or bear : Think what Spirit dwells
within thee ; Think what Father's smiles are thine Think what Jesus
did to win thee : Child of heaven, canst thou repine ? NETTLETON.
8s, 7s. D. J. WYETH S COLL. 181*. rine. ' I I J f Know, my soul, thy
full sal - va - tion; Rise o'er sin and fear and ' (Joy to find, in ev - ery
sta - tion. Something still to do or D. c. Think what Je • sus did to
win thee : Child of heaven, canst thou re care ; \ bear: i pine ? #
«^Fj^l=P=r=T-i 1 1 ^ ^ — «_ J3: r *^ I I Think what Spir - it
dwells with - in thee; Think what Fa-ther's smiles are thine 182
 JOY. DORRNANCE. 8s, 7». 5 t. B. WOODBURY. 1819-1858,
5 I. Sweet the mo - merits, rich in bless - ing. Which be - fore the
cross I spend -\ h From the sin - ner's dy ■ mm Life and health and
peace pos - sess - ing, f . ^ — s — ^—J^—^-a — ^ ing Friend. -fSZ
S_ 3 Truly blessed is this station, Low before his cross to lie ; While I
see divine compassion Beaming in his gracious eye. 4 Here I'll sit,
forever viewing Mercy streaming in his blood ; Precious drops, my
soul bedewing, Plead, and claim my peace with God. W. H. DOANE
JAMES ALLEN. Alt. by WALTER SHIRLEY. 353 1 Sweet the moments,
rich in blessing, Which before the cross I spend ; Life and health and
peace possessing. From the sinner's dying Friend. 2 Love and grief,
my heart dividing. With my tears his feet I'll bathe ; Constant still, in
faith abiding, Life deriving from his death. VINTON. 8s, 78. 61. Al . le
Al ■ le lu - ia! song of gladness. Voice of ev - er - last-ing joy:) lu -
ia! sound the sweetest {Omit.) jHeard among the r t- -r ,P f ip-zf— f
-| — t— ♦ ^ ^ t- ♦ * ^ 7 1 — :> ..> •->..1 1^- • — r — 'i — \ — 1
— ^ .1 ^ — '-\ 1 m choirs on high; Chant-ing in his ho - ly presence,
i Joy and praise e - ter - nal ly. 1 13th century. 1 Alleluia ! song of
gladness. Voice of everlasting joy : Alleluia ! sound the sweetest
Heard among the choirs on high ; Chanting in his holy presence, Joy
and praise eternally. 2 Alleluia! O how faintly Mortal tongues its
raptures raise ; Here our joy is mixed with sadness, Clouding oft our
brightest days ; Here our sweetest songs can never Give to Jesus
worthy praise. 3 But our earnest supplication, Holy God, we raise to
thee; Bring us to thy bUssful presence, Make us all thy joys to see ;
Then we'll sing our hallelujah, — Sing to all eternity.
 THE CHRIfSTIAN, TRUE FRIEND. 6s, 4s. W. H. DOANB. m I.
Now I have found a Friend, Je-sus is mine ; Whose love shall never
end, Je-sus is mine ; 4 1=1: -i& — i-^, I Tho' earthly joys decrease,
Tho' human friendships cease. Now I have lasting peace, Jesus is
mine. ■0^? — f f M # — »355 H. J. m'cracken hope. 1 Now I have
found a Friend, Jesus is mine ; Whose love shall never end, Jesus is
mine ; Though earthly joys decrease, Though human friendships
cease, Now I have lasting peace, Jesus is mine. 2 Though I grow
poor and old, Jesus is mine ; He will my faith uphold, Jesus is mine;
He shall my wants supply. His precious blood is nigh, Naught can my
hope destroy, Jesus is mine. 1852. 3 When earth shall pass away,
Jesus is mine ; In the great judgment day, J esus is mine ; O what a
glorious thing. Then to behold my King, On tuneful harp to sing,
Jesus is mine. 4 Father ! thy name I bless, Jesus is mine; Thine was
the sovereign grace, Jesus is mine ; Spirit of holiness. Sealing the
Father's grace. Thou mad'st my soul embrace Jesus as mine. JESUS
IS MINE, e s, 4s. T. E. PERKINS, by p er. I. Fade, fade each c arthly
joy, Je-sus is \ r?:|r:rri mine ; Break ev-ery t ender tie, Je - sus is 1 u
^-r 1 •^-F-hnine ; Dark is the wilderness, Earth has no resting-
place, Je-sus alone can bless, Je - sus is mine. m 181
 JOY. LEBANON. S. M. D. J. ZtTNDEI.. 1815-1 I. I was a
wandering sheep, I did not love the fold, I did not love my
Shepherd's voice, D. s. I did not love my Father's voice, €-r€ € —
€1=Pt : G f -» — »— * ^1 V Fine. 1?— tI would not be controlled : I
was a wayward child, I loved a -far to roam. did not love my home,
356 HORATIUS BONAR. 1857, 1 I was a wandering sheep, I did not
love the fold ; I did not love my Shepherd's voice, I would not be
controlled : I was a wayward child, I did not love my home ; 1 did
not love my Father's voice, I loved afar to roam. 2 The Shepherd
sought his sheep. The Father sought his child ; He followed me o'er
vale and hill. O'er deserts waste and wild : He found me nigh to
death, Famished and faint and lone ; He bound me with the bands
of love. He saved the wandering one. 3 Jesus my Shepherd is; 'Twas
he that loved my soul, 'Twas he that washed me in his blood, 'Twas
he that made me whole ; 'Twas he that sought the lost, That found
the wandering sheep; 'Twas he that brought me to the fold, 'Tis he
that still doth keep. 4 No more a wandering sheep, I love to be
controlled ; I love my tender Shepherd's voice, I love the peaceful
fold : No more a wayward child, I seek no more to roam ; I love my
heavenly Father's voice, I love, I love his home ! 6s, 4s. CATHARINE
JANE BONAR. ll 1 Fade, fade each earthly joy, Jesus is mine; Break
every tender tie, Jesus is mine. Dark is the wilderness. Earth has no
resting place, Jesus alone can bless, Jesus is mine. 2 Tempt not my
soul away, J esus is mine ; Here would I ever stay, Jesus is mine.
Perishing things of clay Born but for one brief day, Pass from my
heart away ; Jesus is mine. 3 Farewell, ye dreams of night, Jesus is
mine ; Lost in this dawning bright, Jesus is mine. All that my soul
has tried Left but a dismal void; Jesus has satisfied ; Jesus is mine.
185
 THE CHRISTIAN— JOY. HAPPINESS, ns, gs. WESTERN
MELODY. 1. O how hap-py are they Who their Saviour o-bey. And
have laid up their treasure above! Tongue can never express The
sweet comfort and peace Of soul in its ear - li - est love. C. WESLEY.
1749. 1 O how happy are tliey Who their Saviour obey, And have laid
up their treasure above ! Tongue can never express The sweet
comfort and peace Of a soul in its earliest love. 2 That sweet
comfort was mine When the favor divine I had found in the blood of
the Lamb. When at first I believed, What true joy I received ! What a
heaven in Jesus' sweet name ! 3 Jesus all the day long Was my joy
and my song : O that all his salvation might see ! " He hath loved
me," I cried, "He hath suffered and died To redeem such a rebel as
me." PLEYEL'S HYMN. 7s. I. PLEY EL. 1757 -1831. 1. Children of the
heavenly King, As ye jonrney, sweetly sing ; Sing your Saviour's \
Forthy praise, Glorious in iis works a [yr 1 #-1 nd ways. tJt9U JOHN
CENNICK. I742. 1 Children of the heavenly King, As ye journey,
sweetly sing ; Sing your Saviour's worthy praise, Glorious in his
works and ways. 2 Ye are traveling home to God, In the way the
fathers trod; VIENNA. 7s. They are happy now, and ye Soon their
happiness shall see. 3 Lord, submissive make us go. Gladly leaving
all below ; Only thou our Leader be. And wfi still will follow thee.
ARR. J. H. KNECHT. 1752-I795. 1. Children of the heavenly King, As
ye jonrney, sweetly sing ; Sing your Saviour's worthy praise, Glorious
in his works and ways. mm 186
 ASPIRATION. BLESS ME NOW. 7s 3 REV. ROBERT LOWRY. I.
Heavenly Father, bless me now ; At the cross of Christ I bow ; Take
my guilt and grief away ; REFRAIN. Nt Hear and heal me now, I
pray. Bless me now, bless me now ; Heavenly Father, bless me now.
-1 1 »— -» F — P — H — ^ ■ ' 360 ALEXANDER CLAKK. 1834-1881.
1 Heavenly Father, bless me now ; At the cross of Christ I bow; Take
my guilt and grief away ; Hear and heal me now, I pray. Ref. — Bless
me now, bless me now ; Heavenly Father, bless me now. 2 Now, O
Lord ! this very hour, Send thy grace and show thy power ; "While I
rest upon thy word. Come and bless me now, O Lord ! 3 Now, O
now, for Jesus' sake. Lift the clouds, the fetters break; While I look,
and as I cry. Touch and cleanse me ere I die. 4 Never did I so adore
Jesus Christ, thy Son, before; Now the time ! and this the place I
Gracious Father, show thy grace. 1 ^ Ine. 1 REFR>i TM. I>. c. 1 /
Pass me not, 0 gen-tle Saviour, Hear my humble cry ; \ ' I While on
others thou art smiling, (Omr^.) . . ./Do no B.C. While on others
thou art calling, (Omil) . . . Do not t 1 pass me pass me ». » » by.
Saviour, 8ar-iour,hearm f humble cry 1 -U 1 — L-b_ 361 F. J. VAN
ALSTVNE. 1869. 1 Pass me not, 0 gentle Saviour, Hear my humble
cry ; While on others thou art smiling, Do not pass me by. Ref.—
Saviour, Saviour, Hear my humble cry; While on others thou art
calling. Do not pass me by. 2 Let me at thy throne of mercy Find a
sweet relief; 13 187 Kneeling there in deep contrition, Help my
unbeHef. 3 Trusting only in thy merit. Would I seek thy face; Heal
my wounded, broken spirit; Save me by thy grace. 4 Thou the spring
of all my comfort, More than life to me. Whom have I on earth
beside thee ? Whom in heaven but thee ?
 THE CHRISTIAN. Eventide, ios. W. tt. MONK. 33 I. Abide
with me ! Fast falls the e-ven - tide ; The darkness deepens— Lord,
with me abide f ^ /ti When oth-er help-ers fail, and comforts flee,
Help of the helpless, O a - bide with me ! *i J i ^ . _ J , , . . ^ J. I
2=1 i — t363 H. F. LYTB. 1847. 1 Abide with me! Fast falls the
eventide; The darkness deepens— Lord, with me abide! When other
helpers fail, and comforts flee, Help of the helpless, O abide with me
! 2 Swift to its close ebbs out life's little day; Earth's joys grow dim,
its glories pass away; Change and decay in all around I see; O thou,
who changest not, abide with me! 3 I need thy presence every
passing hour, What but thy grace can foil the tempter's power ?
W^ho, like thyself, my guide and stay can be? Through cloud and
sunshine, O abide with me! 4 Hold thou thy cross before my closing
eyes; Shine through the gloom, and point me to the skies; Heaven's
morning breaks, and earth's vain shadows flee! In life, in death, O
Lord, abide with me ! I NEED THEE. P. M REV. ROBERT LOWRY. 1. I
need thee every hour. Most gracious Lord ; No tender voice like thine
Can peace af-ford. 1 1 need thee, O, I need thee ; Every hour I need
thee ; O bless me now, my Saviour ! I come to thee. 188
 ASPIRATION. CONSTANCE. 8s, 7s, 49. W. tt. COANE. r r r J
f Gently, Lord, O gen-tly lead us, Thro' this gloomy vale of tears;)
(And, O Lord, in mer-cy give us i^Omit.) . 3 Thy rich grace in -Jrr1
— ti — iall our fears. O -/Stre- fresh us, O re-fresh us, Traveling
through this wil -der - ness. 363 THOMAS HASTINGS. 1832. 1
Gently, Lord, O gently lead us, Through this gloomy vale of tears ;
And, O Lord, in mercy give us Thy rich grace in all our fears. O
refresh us, O refresh us. Traveling through this wilderness. 2 When
temptation's darts assail us, When in devious paths we stray, Let thy
goodness never fail us, Lead us in thy perfect way. O refresh us, O
refresh us, TraveUng through this wilderness. GREENVILLE 1 h 3 In
the hour of pain and anguish, In the hour when death draws near,
Suffer not our hearts to languish, Suffer not our souls to fear. O
refresh us, 0 refresh us, Traveling through this wilderness. 4 When
this mortal life is ended, Bid us in thine arms to rest. Till, by angel
bands attended, We awake among the blest. O refresh us, O refresh
us, Traveling through this wilderness. And, 0 Lord, in mer-cy give us
\ re-fresh us, Travelfng through this wil-der-ness. \ Thy rich grace in
all our {Omit.) ] fears. Gen-tly, Lord, 0 gen-tly lead us, Through this
gloomy vale of tears; / And, 0 Lord, in mer-cy give us D. c. 0 re-
fresh us, 0 ANNIE S. HAWKS. 364 p. M. 1 I need thee every hour,
Most gracious Lord ; No tender voice like thine Can peace afford.
Ref. — I need thee, O, I need thee; Every hour I need thee ; O bless
me now, my Saviour ! I come to thee. 2 I need thee every hour;
Stay thou near by ; Temptations lose their power When thou art
nigh. 3 I need thee every hour ; Teach me thy will ; And thy rich
promises In me fulfill. 4 I need thee every hour, Most Holy One ; O
make me thine indeed, Thou blessed Son, 189
 THE CHRISTIAN. DRAW ME NEARER. P. M. S W. H. DOANE.
I 1st I am thine, 0 Lord ; I have heard thy voice, And it told thy love
to me ; ) But I long to rise in the arms of faith, ( Omit.) / And be
closer drawn to thee. Draw me near ■ er, • S^ . - . ^ nearer, blessed
Lord, To the cross where thou hast died ; Draw me nearer, nearer,
nearer, blessed Lord, To thy precious bleeding side. 365 FRANCES
JANE VAN ALSTYNE. 1875. 1 1 am thine, O Lord ; I have heard thy
voice, And it told thy love to me; But I long to rise in the arms of
faith, And be closer drawn, to thee. Ref. — Draw me nearer, nearer,
blessed Lord, To the cross where thou hast died ; Draw me nearer,
nearer, nearer, blessed Lord , To thy precious bleeding side. 2
Consecrate me now to thy service, Lord, By the power of grace
divine ; Let my soul look up with a steadfast hope, And my will be
lost in thine. 3 O the pure delight of a single hour That before thy
throne I spend, When I kneel in prayer, and with thee, my God, I
commune as friend with friend. 4 There are depths of love that I can
not know Till I cross the narrow sea ; There are heights of joy that I
may not reach Till I rest in peace with thee. LOVE DIVINE 8s, 7s.
Fine. Arr. from Gregorian 2d. JD.C 1 I J r Love di-vine, all love ex-cel-
ling, Joy of heaven, to earth come down! \ f Jesus, thou art all
compassion, I Fix in us thy humble dwell-ing ; All thy faithful mer-
cies crown. / I Pure, unbounded ( Omit. D. c. Vis - it us^with thy
sal-va-tion, En - ter ev-ery trembling heart. love thou art. CHARLES
WESLEY. 1746. 366 1 Love divine, all love excelling, Joy of heaven,
to earth come down 1 Fix in us thy humble dwelling ; All thy faithful
mercies crown. Jesus, thou art all compassion, Pure, unbounded love
thou art; Visit us with thy salvation. Enter every trembling heart 2
Breathe, O breathe thy Holy Spirit Into every troubled breast ; Let us
all thy grace inherit^ Let us find thy promised rest; Take away the
love of sinning ; Take our load of guilt away ; End the work of thy
beginning ; Bring us to eternal day. 190 [For 3d verse, see next
page.]
 ASPIKATION. BLUMENTHAL. 7s. D. J. BLUMENTHAL.
18241.1,4 1., 4-4-4-J . / ■ j-t-rn I. lore like Jesus would 1 be, Let my
Savioul dwell in me ; Fill my soul with -y— #1 — 1 S^L^ leace and
love, Make me ftz^L — L gentle a s a dove; ^=?^^41 1 i— tFt— ^
More like Jesus, while I go, Pilgrim in this world be-low ; Poor in
spir-it would I be,— Let my Saviour dwell in me. -t~l-^| 367
FRANCES JANE VAN ALSTYNE. 1 1 More like Jesus would I be, Let
my Saviour dwell in me ; Fill my soul with peace and love, Make me
gentle as a dove ; More like Jesus, while I go, Pilgrim in this world
below ; Poor in spirit would I be, — Let my Saviour dwell in me. 2 If
he hears the raven's cry. If his ever-watchful eye Marks the sparrows
when they fall, Surely he will hear my call. MORE LIKE JESUS. 7s. D.
He will teach me how to live, All my sinful thoughts forgive ; Pure in
heart I still would be, — Let my Saviour dwell in me. 3 More like
Jesus when I pray. More like Jesus day by day ; May I rest me by his
side, Where the tranquil waters glide, Born of him, through grace
renewed. By his love my will subdued, Rich in faith I still would be,
— Let my Saviour dwell in me. W. H. DOANE. I. More like Jesus
would I be, Let my Saviour dwell in me ; Fill my soul with peace and
love, D. s. Poor in spir - it would I be, — ^^^^^^^ SSI ». s. Make
me gentle as a dove; More like Jesus, while I go, Pilgrim in this
world below ; Let my Saviour dwell in me. T^, ^ ^—^ ^ , 1 * .. 3
Carry on thy new creation ; Pure and holy may we be ; Let us see
our whole salvation Perfectly secured by thee ; Change from glory
into glory. Till in heaven we take our place, Till we cast our crowns
before thee. Lost in wonder, love, and praise.
 THE CHRISTIAN. BERA. L. M. J. E. GOULD. 1822-1875. is:
X. Come, gra-cious Lord, de - scend and dwell, By faith and love, in
ev - ery breast ; s 1^ 1 1Then shall we know and taste and feel -
ItThe joys that can not be ex - pressed. i I -I \ ISAAC WATTS, I709.
368 1 Come, gracious Lord, descend and dwell, By faith and love, in
every breast ; Then shall we know and taste and feel The joys that
can not be expressed. 2 Come, fill our hearts with inward strength,
Make our enlarged souls possess, And learn the height and breadth
and length Of thine eternal love and grace. 3 Now to the God whose
power can do More than our thoughts and wishes know. Be
everlasting honors done, By all the church, through Christ his Son.
369 CHARLES WESLEY. I742. 1 O that my load of sin were gone ! O
that I could at last submit At Jesus' feet to lay it down. To lay my
soul at Jesus' feet 1 2 Rest for my soul I long to find ; Saviour of all,
if mine thou art. Give me thy meek and lowly mind, And stamp thine
image on my heart. 8 Fain would I learn of thee, my God, Thy light
and easy burden prove ; The cross, all stained with hallowed blood,
The labor of thy dying love. 4 I would, but thou must give the power
: My heart from every sin release ; Bring near, bring near the joyful
hour, And fill me with thy perfect peace. 370 ISAAC WATTS. 1 What
sinners value I resign ; Lord, 'tis enough that thou art mine; 1 shall
behold thy blissful face, And stand complete in righteousness. 2 This
life's a dream, an empty show; But that bright world to which I go
Hath joys substantial and sincere ; When shall I wake and find me
there ? 3 O glorious hour ! O blest abode ! I shall be near and like
my God ; And flesh and sin no more control The sacred pleasures of
the soul. 4 My flesh shall slumber in the ground, Till the last
trumpet's joyful sound. Then burst the chains with sweet surprise.
And in my Saviour's image rise. 371 ANNE STEELE. 1760. 1 Jesus
demands this heart of mine — Demands my wish, my joy, my care;
Biit, ah ! how dead to things divine. How cold, my best affections are
! 2 'Tis sin, alas ! with dreadful power, Dividec m;. Saviour from my
sight ; O for one happy, shining hour Of sacred freedom, sweet
delight! 3 O let thy love shine forth and raise My captive powers
from sin and death, And fill my heart and life with praise, And tune
my last expiring breath. 182
 ASPIEATTON. ROWLAND. L. M. S. p. TUCKERMAN. I. My
God, per - mit me not Si to be A stran-ger to my - self and thee;
J^J-^- 7^— r:*^ to t:=|: -0- -9- \ i - I A - midst a thousand
thoughts I rove, For - get - ful of J ^ . 1 my high - est love. 372
ISAAC WATTS. 1709. 1 My God, permit me not to be A stranger to
myself and thee ; Amidst a thousand thoughts I rove, Forgetful of
my highest love. 2 Why should my passions mix with earth, And thus
debase my heavenly birth ? Why should I cleave to things below,
And let my God, my Saviour, go? 3 Call me away from flesh and
sense ; One sovereign word can draw me thence ; I would obey the
voice divine. And all inferior joys resign. 4 Be earth, with all her
scenes, withdrawn ; Let noise and vanity be gone; In secret silence
of the mind My heaven, and there my God, I find. *> PAUL
GERHARDT. 1653. 0 % Tr. by John vvesley. 1739. 1 Jesus, thy
boundless love to me No thought can reach, no tongue declare ;
Unite my thankful heart to thee, And reign without a rival there. 2
Thy love, how cheering is its ray ! All pain before its presence flies ;
Care, anguish, sorrow, melt away. Where'er its healing beams arise.
3 O let thy love my soul inflame, , And to thy service sweetly bind ;
Transfuse it through my inmost frame, And mold me wholly to thy
mind. 4 Thy love, in suflerings, be my peace ; Thy love, in
weakness, make me strong ; And, when the storms of life shall
cease, Thy love shall be in heaven my song. LUTHER'S CHANT. L. M.
i H. C. ZEUNER. 1795-1852. 3 I. Je - sus, thy boundless love to me
No thought can reach, no tongue de - clare ; -G U - nite my thankful
heart to thee, And reign with-out a If .r . ^ r .-^ ,r ,f- f f f val there.
J2193 -r
 THE CHKISTIAN. NAOMI DR. LOWELL MASON. 1792-1874.
I. Father, whate'er of earthly bliss Thy sovereign will denies,
Accepted at thy throne of grace, let this pe- ti-tion rise : — I ANNE
STEELE. I760. 374 1 Father, whate'er of earthly bliss Thy sovereign
will denies, Accepted at thy throne of grace, Let this petition rise : —
2 Give me a calm, a thankful heart. From every murmur free ; The
blessings of thy grace impart. And make me live to thee. 3 Let the
sweet hope that thou art mine My life and death attend ; Thy
presence through my journey shine, And crown my journey's end.
375 WILLIAM COWPER. 1779. 1 O for a closer walk with God, A
calm and heavenly frame, A light to shine upon the road That leads
me to the Lamb ! 2 Where is the blessedness I knew When first I
saw the Lord ? Where is the soul-refreshing view Of Jesus and his
word ? 3 What peaceful hours I then enjoyed ! How sweet their
memory still ! But they have left an aching void The world can never
fill. 4 Return, O Holy Dove, return. Sweet messenger of rest; I hate
the sins that made thee mourn, And drove thee from my breast.
ELIZABETHTOWN. C. M. 5 The dearest idol I have known, Whate'er
that idol be. Help me to tear it from thy throne. And worship only
thee. 376 BENJAMIN CLEAVELAND. 1792. 1 O could I find from day
to day, A nearness to my God ! Then would my hours glide sweet
away. While leaning on his word. 2 Lord, I desire with thee to live
Anew from day to day, In joys the world can never give, Nor ever
take away. 3 Blest Jesus, come, and rule my heart, And make me
wholly thine. That I may never more depart. Nor grieve thy love
divine. 377 JOHN S. B. MONSELL. 1863. 1 I think of thee, my God,
by night. And talk of thee by day ; Thy love my treasure and delight,
Thy truth my strength and stay. 2 The day is dark, the night is long,
Unblest with thoughts of thee, And dull to me the sweetest song,
Unless its theme thou be. 3 So all day long, and all the night. Lord,
let thy presence be, Mine air, my breath, my shade, my light, Myself
absorbed in thee. GEORGE KINGSLEY. 1. 1 think of thee, my God, by
night, And talk of thee by day ; Thy love ray treasure and delight.
Thy truth my strength and stay. 194
 ASPIRATION. DOWNS. C. M. DR. LOWELL MASON. 1792-
1872. 1. 0 for a heart to praise my God, A heart from sin set free; A
heart that's sprinkled with the blood So freely shed for me. ^-0 9i
378 CHARLES WESLEY. I742. 1 O for a heart to praise my God, A
heart from sin set free ; A heart that's sprinkled with the blood So
freely shed for me. 2 O for a heart submissive, meek. My great
Redeemer's throne. Where only Christ is heard to speak, Where
Jesus reigns alone. 3 Thy temper, gracious Lord, impart; Come
quickly from above ; 0 write thy name upon my heart! Thy new, best
name of love. 379 WILLIAM H. BATHURST. 1831. 1 O for a faith that
will not shrink, Though pressed by every foe. That will not tremble
on the brink Of any earthly woe ; — 2 That will not murmur nor
complain Beneath the chastening rod. But, in the hour of grief or
pain. Will lean upon its God ; — 3 A faith that shines more bright
and clear When tempests rage without ; That, when in danger,
knows no fear, In darkness feels no doubt. 4 Lord, give us such a
faith as this, And then, whate'er may come. We'll taste, e'en here,
the hallowed bliss Of an eternal home. TATE AND BRADY. 1696. 380
1 As pants the hart for cooling streams When heated in the chase,
So pants my soul, O Lord, for thee, And thy refreshing grace. 2 For
thee, my God, the living God, My thirsty soul doth pine ; 0 when
shall I behold thy face. Thou majesty divine ? 3 Why restless, why
cast down, my soul? Trust God, and thou shalt sing His praise again,
and find him still Thy health's eternal spring. 381 ELIZABETH MILLS.
1 Sweet land of rest, for thee I sigh ; When will the moment come.
When I shall lay my armor by. And dwell with Christ at home ? 2 No
tranquil joys on earth I know. No peaceful sheltering dome : This
world's a wilderness of woe, — This world is not my home. 3 To
Jesus Christ I sought for rest ; He bade me cease to roam, But fly
for succor to his breast, And he'd conduct me home. 4 Weary of
wandering round and round This vale of sin and gloom, I long to
leave th' unhallowed ground, And dwell with Christ at home. ST.
MARK. C. M. H. J. GAUNTLETT. 1806-1876. U41. Sweet land of rest,
for thee I sigh : When will the moment come, When 1 shall lay my
armor by, And dwell with Christ at home P
 THE CHRISTIAN. AUKLAND. 6s, 5s. D. T. B. AYLWARD. m —
#— * I. Saviour, blessed Saviour, Listen while we sing, Hearts and
voices raising Praises to our King ; U-J-4-J: I All we have we of - fer ;
All we hope to I be, Body, soul, and spirit. All we yield to thee. I
Thou for our redemption, Cam'st on earth to die ; Thou, that we
might follow, Hast gone up on high. 3 Great and ever greater Are
thy mercies here, True and everlasting Are the glories there, Where
no pain nor sorrow, Toil nor care is known ; Where the angel-legions
Circle round thy throne. G. A. HARDACRH. 382 GODFREY THRING.
I»()2. 1 Saviour, blessed Saviour, Listen while we sing. Hearts and
voices raising Praises to our King; All we have we offer; All we hope
to be. Body, soul, and spirit, All we yield to thee. 2 Nearer, ever
nearer, Christ, we draw to thee, Deep in adoration Bending low the
knee : CONWAY. 6s, 5S. — 1867. Jesus, meek and gentle, Son of
God most high, Pitying, loving Saviour, Hear thy children's cry. 1 1
383 GEORGE RUNDELL PRYNNE. 1856. 1 Jesus, meek and gentle.
Son of God most high. Pitying, loving Saviour, Hear thy children's cry.
2 Pardon our offenses, Loose our captive chains : Break down every
idol Which our soul detains. 3 Give us holy freedom, Fill our hearts
with love, Draw us, holy Jesus, To the realms above. 4 Lead us on
our journey : Be thyself the way Through terrestrial darkness To
celestial day. 190
 ASPIRATION. FAITH. 6s, 48. JOHN HENRY CORNELL. 1872.
— «— — N [. My faith looks up to thee, Thou Lamb of Cal - va - ry,
Sav-iour di - vine 'i Now hear me is: -I — 1while I pray, Take all my
guilt a-way, let me from this day Be wholly thine. 384 RAY PALMER.
1830. 1 My faith looks up to thee, Thou Lamb of Calvary, Saviour
divine ! Now hear me while I pray, Take all my guilt away ; O let me
from this day Be wholly thine. 2 May thy rich grace impart Strength
to my fainting heart ; My zeal inspire ; As thou hast died for me, O
may my love to thee Pure, warm, and changeless be, A living fire. Bj
per. J. P. YouDg 4 Co., N. Y. 3 While life's dark maze I tread, And
griefs around me spread, Be thou my guide ; Bid darkness turn to
day, Wipe sorroAv's tears away, Nor let me ever stray From thee
aside. 4 When ends life's transient dream, When death's cold, sullen
stream Shall o'er me roll, Blest Saviour, then, in love. Fear and
distress remove ; O bear me safe above, A ransomed soul. OLIVET.
6s, 4s. DR. LOWELL MASON. 1792-1872. 1. My faith looks up to
thee, Thou Lamb ot Cal-va - ry, Sav - iour di - vine ! Now hear me
i-:-r-r=:^ 1 i while I pray. Take all my guilt a-way ; O let me from
this day Be whol - ly thine. f—rw 197
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

textbookfull.com