Digital PDFs

AA-MA95B-TE

May 1989

439 pages

Original

15MB

Document:	ULTRIX Worksystem Software Guide to the XUI Toolkit: C Language Binding
Order Number:	AA-MA95B-TE
Revision:	0
Pages:	439
Original Filename:

OCR Text

ULTRIX Worksystem Software

Guide to the XUI Toolkit:
C Language Binding

Order Number: AA-MA95B-TE

Product Version:
Operating System and Version:

digital equipment corporation
maynard, massachusetts

ULTRIX Worksystem Software, Version 2.2
ULTRIX-32 Version 3.1 and higher

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as
set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause of
DFARS 252.227-7013.

The information in this document is subject to change without notice and should not be construed as a
commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no
responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or copied only in
accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied by
Digital or its affiliated companies.

This manual is derived from MIT documentation, which contains the following permission notice:
Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appears in all copies and that both that
copyright notice and this permission notice appear in supporting documentation, and that the name of
MIT or DIGITAL not be used in advertising or publicity pertaining to distribution of the software
without specific, written prior permission. MIT and DIGITAL make no representations about the
suitability of the software described herein for any purpose. It is provided "as is," without express or
implied warranty.
UNIX is a registered trademark of AT&T in the USA and other countries.
X Window System, X, and XII are registered trademarks of MIT.
The following are trademarks of Digital Equipment Corporation:
CDA
DECnet
DDIF
MicroVAX
ULTRIX Mail Connection
VAXstation
VT

DEC
DEC station
DDIS
Q-bus
ULTRIX Worksystem Software
VMS
XUI

DECUS
DECwindows
DTIF
ULTRIX
VAX
VMS/ULTRIX Connection

~D~DDmD

This manual was written and produced by the Open Software Publications group.

Contents

About This Manual
Audience

Organization

............................................. , . . . . ... .. . . . . . . . .. . .. . .. .. .. .. . .. . . . . . . .

Related Documentation

.. ,. . .. ... . .. . . .. .. . .. . . . . . . . . . . . . . .. . .. . .. . . . . .. . . . . .. .. .. . . . . . . . . . . . .

XXIII

xxiii
xxiii

Conventions

Summary of Technical Changes
Additions and Changes to High-Level Widget and Widget Convenience
Functions ........................................................................... .

xxv

New High-Level Widget and Widget Convenience Functions ......... ..
Changes to High-Level Functions ................................................ .
Changes to DwtDialogBox ......................................................... .

xxvi
xxvi
xxvn

Changes to DwtListBoxltemExists ...................................... .
Changes to DwtMenu ........................................................ .
Changes to DwtOptionMenu ............................................... .
Changes to DwtScale ......................................................... .

xxvii
xxvii
xxvii
XXVIll

....................... ..

xxviii

New Low-Level Widget Functions .............................................. .
Changes to Low-Level Functions ............................................... ..

xxviii
xxix

Changes to DwtAttachedDBCreate ...................................... .
Changes to the DwtNdestroyCallback and DwtNdirectionRToL
Attributes ........................................................... .
Changes to DwtDialogBoxCreate ........................................ .
Changes to DwtDialogBoxPopupCreate ............................... .

XXIX

Additions and Changes to Low-Level Widget Functions

xxix
xxix
xxxn

Changes to DwtFileSelectionCreate .... . ... .. ... . .. . . .. .. . .. . .. . .. . .. ... .
Changes to DwtHelpCreate ..................................................
Changes to DwtMenuCreate, DwtMenuBarCreate,
DwtOptionMenuCreate, and DwtRadioBoxCreate
Changes to DwtMenuPopupCreate and
DwtMenuPulldownCreate ......................................
Changes to DwtMessageBoxCreate ....... ,...............................
Changes to DwtPushButtonCreate ........................................
Changes to DwtSTextCreate ................................................
Changes to DwtScaleCreate .... .. . .. . .... . .... .. . . .. .. . .. .... .. ... . .. .... ...
Changes to DwtScrollBarCreate .... .. . ... .... . .... .. . .. . ... .. . ... .. . ... .. .
Changes to DwtToggleButtonCreate .....................................
Additions and Changes to Cut and Paste Functions

xxxii
xxxv
xxxv
xxxvi
xxxvii
xxxviii
xxxviii
xxxviii
xxxviii
xxxix
xxxix

New Cut and Paste Functions ......................................................
Changes to Cut and Paste Functions .. . .. . ..... ... . .. . . .... . .. . . .. .. ... . .. .. .. .. .

xxxix
xl

Changes to DwtCopyFromClipboard .....................................
Changes to DwtInquireNextPasteCount,
DwtInquireNextPasteFormat, and
DwtInquireNextPasteLength ...................................

Additions and Changes to Compound String Functions

xli
xli

New Compound String Functions .................................................
Changes to Compound String Functions ........................................

xli
xli

Changes to DwtAddFontList, DwtCreateFontList, and
DwtGetNextSegment .............................................
Changes to DwtInitGetSegment ............................................

xli
xli

New Convenience Functions

................................................................

xlii

Programming Considerations

1.1

Methods for Creating Widget Instances

1-1

1.1.1
1.1.2

1-1
1-2

1.1.3
1.2

High-Level Functions
Low-Level Functions
User Interface Language

Widget Class Hierarchy

ivContents

1-3
1-3

1.3

Common Attributes

1-5

1.4

Include Files

1-8

1.5

The Callback Facility

1.6

Function Format

Window Widget Functions

2.1

Creating the Application Main Window

2.1.1
2.1.2
2.1.3
2.1.4
2.2

2.3

2.4

1-8
1-11

.......................................

2-1

Callback Information .......................................................
Geometry Management ....................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

2-3
2-4
2-5
2-7

...............................................................

2-8

Callback Information . .. .. .. . . . .. . .. . .. . .. . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . .
Widget Class Hierarchy and Inherited Attributes .................

2-10
2-10

Creating the Menu Bar

2.2.1
2.2.2

................................................................ .

Creating a Window Widget

2-13

2.3.1
2.3.2
2.3.3

2-14
2-15
2-16

Callback Information ...................................................... .
Widget Class Hierarchy and Inherited Attributes ................ .
Widget-Specific Attributes .............................................. .

Creating a Scroll Window Widget

2-17

2.4.1
2.4.2
2.4.3

2-18
2-19
2-20

Geometry Management and Resizing ................................ .
Widget Class Hierarchy and Inherited Attributes ................ .
Widget-Specific Attributes ............................................. ..

2.5

Adding Subwidgets to the Main Window

2-21

2.6

Adding a Window Region and Scroll Bar

2-22

Subarea Widget Functions

3.1

Creating the Scroll Bar

3.1.1

Callback Information

3-1
...................................................... .

3-5

Contents v

3.1.2
3.1.3
3.1.4

3.2

Obtaining and Setting the Scroll Bar Slider Size/position

3.3

Creating a Label Widget

3.3.1
3.3.2
3.3.3
3.4

...............

3-11

............................................................

3-13

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

3-14
3-15
3-16

................................................

3-18

Callback Information .......................................................
Geometry Management and Resizing .................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

3-20
3-20
3-21
3-23

Creating a Toggle Button Widget

3.4.1
3.4.2
3.4.3
3.4.4

...................

3-25

.....................................................

3-26

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................

3-27
3-28

3.5

Obtaining and Setting the Toggle Button Widget State

3.6

Creating a Radio Box Widget

3.6.1
3.6.2
3.7

3.8

3-30

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

3-32
3-33
3-35

......................... ....................................

3-37

3-40
3-40
3-41
3-42

Creating a Scale Widget

3.8.1
3.8.2
3.8.3
3.8.4
3.9

.. .................................................

Creating a Push Button Widget

3.7.1
3.7.2
3.7.3

Obtaining and Setting the Scale Slider Position

vi Contents

3-6
3-7
3-8

3-43

Menu Widget Functions

4.1

Creating Menu Widgets

4.1.1

............................................................ .

4-1

Creating Pull-Down, Pop-Up, and Menu Work Area Widgets .

4-2

4.1.1.1
4.1.1.2
4.1.1.3
4.1.1.4
4.2

4-15

Callback fuformation ...................................................... .
Geometry Management and Resizing ................................ .
Widget Class Hierarchy and Inherited Attributes ................ .
Widget-Specific Attributes .............................................. .

4-17
4-17
4-18
4-19

............................................... .

4-20

Callback fuformation ...................................................... .
Widget Class Hierarchy and Inherited Attributes ................ .
Widget-Specific Attributes .............................................. .

4-22
4-23
4-25

Creating an Option Menu Widget

4.3.1
4.3.2
4.3.3
4.4

Menu Convenience Functions

4.5

Creating a Separator Widget

4.5.1
4.5.2

4-25
...................................................... .

4-26

Widget Class Hierarchy and Inherited Attributes ................ .
Widget-Specific attributes ............................................... .

4-28
4-29

Dialog Box and Text Widget Functions

5.1

Creating a Dialog Box Widget

5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
5.1.6
5.2

4-5
4-5
4-6
4-10

.................................... .

Creating Pull-Down Menu Entry Widgets

4.2.1
4.2.2
4.2.3
4.2.4
4.3

Callback Information ........................................... .
Geometry Management and Resizing ..................... .
Widget Class Hierarchy and Inherited Attributes
Widget-Specific Attributes .................................... .

....................................................

5-1

Callback Information .......................................................
Geometry Management ....................................................
Resizing ... .. . .. . ... . .. .. ... .. ........ .. . . .. .. ... ... . .. . ... .. . . .. ... ..... . .. . .. .
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................
Constraint Attributes . .......... .......... .... .. . .. . . . . .. .... .. . .. . ... .. . ...

5-5
5-6
5-6
5-6
5-8
5-13

Creating an Attached Dialog Box Widget

5-13

Contents vii

5.2.1
5.2.2
5.2.3
5.2.4
5.3

Creating a Simple Text Widget

5.3.1
5.3.2
5.3.3
5.4

5.4.4
5.4.5

5.6.4
5.6.5

Clearing, Obtaining, and Setting the Global Selection ......... .
Obtaining and Displaying a New Text String .................... ..
Obtaining and Setting the Maximum Length of the Simple
Text Widget ................................................................ .
Obtaining and Setting Editing Information About the Text
Replacing Part of the Old Text ........................................ .
.................................. ..

5-17
5-17
5-21
5-22
5-27
5-28
5-29
5-30
5-33
5-34
5-35
5-35
5-36
5-37
5-37
5-39
5-40
5-41
5-45
5-45
5-46
5-47
5-48
5-48

.................................................... ..

5-49

5-51
5-52
5-54

Manipulating a Color Mix Widget

viii Contents

............................ .

Clearing, Obtaining, and Setting the Global Selection ......... .
Obtaining and Displaying a New Compound String Text
Obtaining and Setting the Maximum Length of the
Compound String Text Widget ...................................... .
Obtaining and Setting Editing Information About the
Compound String Text Widget ..................................... ..
Replacing Part of the Old Text in the Compound String Text
Widget ....................................................................... .

Creating a Color Mix Widget

5.7.1
5.7.2
5.7.3
5.8

........................................... .

Manipulating a Compound String Text Widget

5.6.1
5.6.2
5.6.3

5.7

Callback Information ..................................................... ..
Widget Class Hierarchy and Inherited Attributes ............... ..
Widget-Specific Attributes .............................................. .

Creating a Compound String Text Widget

5.5.1
5.5.2
5.5.3
5.6

.................................................. .

Manipulating a Simple Text Widget

5.4.1
5.4.2
5.4.3

5.5

5-59

5.9

5.9.1
5.9.2
5.9.3
5.9.4
5.10

....................................................... .

5-60

Callback Information ...................................................... .
Geometry Management and Resizing ................................ .
Widget Class Hierarchy and Inherited Attributes ................ .
Widget-Specific Attributes .............................................. .

5-63
5-64
5-65
5-66

Creating a List Box Widget

5-69

List Box Convenience Functions

5.10.1
5.10.2
5.10.3
5.10.4
5.10.5
5.10.6
5.10.7
5.10.8
5.10.9

Adding and Deleting Items to a List Box Widget ............. .
Deleting an Item By Position ......................................... .
Deselecting a Single Item or All Previously Selected Items
Verifying the Existence of an Item ................................. .
Selecting an Item in the List Box ................................... .
Setting the Horizontal Position ...................................... .
Making an Item the First Visible Item in the List Box
Making a Position the Top Visible Position in the List Box
Selecting and Deselecting an Item by Its Positiion in the List
Box ........................................................................... .

Standard Menus and Dialog Box Widget Functions

6.1

Creating the Help Menu Widget

6.1.1
6.1.2
6.1.3
6.2

6.3

6.4

6-1

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

6-4
6-4
6-6

..................................

6-12

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget Class Hierarchy and Inherited Attributes .................

6-14
6-14
6-16

.................................................

6-17

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

6-19
6-20
6-22

Creating a Message Box Widget

6.3.1
6.3.2
6.3.3

...................................................

6-23

.......................................................

6-26

Creating a Caution Box Widget

6.4.1

5-74

........................................... .......

Creating the Work-in-Progress Box Widget

6.2.1
6.2.2
6.2.3

5-69
5-70
5-71
5-71
5-72
5-72
5-72
5-73

Callback Information

Contents ix

6.4.2
6.4.3
6.5

Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

Creating the Command Window

6--29

6.5.1
6.5.2
6.5.3

6--31
6--32
6--34

6.6

Manipulating the Command Line

6.7

Creating a Selection Box Widget
6.7.1
6.7.2
6.7.3

6.8

6-26
6--28

6--35
.................................................

6--36

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

6--39
6--39
6--41

Creating a File Selection Box Widget
6.8.1
6.8.2
6.8.3

..........................................

6--43

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

6--46
6--47
6--49

6.9

Initiating a Search with a Directory Mask Option

Gadget Functions

7.1

Classes Associated with Gadgets

7-1

7.2

Advantages of Using Gadgets

7-2

7.3

X Intrinsics and Convenience Functions Used with Gadgets

7.4

Creating a Label Gadget
7.4.1
7.4.2
7.4.3

7.5

...........

7-2

.............................................................

7-3

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

7-4
7-4
7-5

Creating a Push Button Gadget
7.5.1
7.5.2
7.5.3

x Contents

6--51

...................................................

7-6

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

7-7
7-7
7-8

7.6

7.7

Creating a Separator Gadget

7-9

7.6.1
7.6.2

7-10
7-10
7-11

Creating a Toggle Button Gadget

7.7.1
7.7.2
7.7.3
7.8

Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

7-14

Callback Information .......................................................
Widget Class Hierarchy and Inherited Attributes .................
Widget-Specific Attributes ...............................................

7-15
7-16
7-17

Creating a Pull-Down Menu Entry Gadget

7.8.1
7.8.2
7.8.3

7-12
7-12
7-13

Cut and Paste Functions

8.1

Introduction to the Cut and Paste Functions

8-1

8.2

ICCCM Compliant Functions and ICCCM Formats

8-3

8.3

Setting Up Storage and Data Structures

8-4

8.3.1
8.3.2
8.4

....................................... .

Using DwtStartCopyFromClipboard to Set Up Storage and
Data Structures ............................................................ .
Using DwtBeginCopyToClipboard to Set Up Storage and
Data Structures ............................................................ .

Indicating That the Application No Longer Wants to Supply a Data
Item ................................................................................... .
.................................................. .

.............................................................. .

8-10

Canceling a Copy to Clipboard

8.6

Locking the Clipboard

8.7

Unlocking the Clipboard

8.8

Retrieving a Data Item from the Clipboard

8.8.2

8.9

8-7

8-8
8-9

8.5

8.8.1

8-5

8-11
.................................. .

8-12

Using DwtStartCopyFromClipboard and
DwtEndCopyFromClipboard ......................................... .
Using DwtCopyFromClipboard ....................................... .

8-12
8-14

Copying a Data Item to the Clipboard

8-16

Contents xi

8.10

Placing Data in the Clipboard

8.11

Returning the Number of Data Item Formats

8.12

Returning a Specified Format Narne

8.13

Returning the Length of the Stored Data

8.14

Returning a List of Data ID/Private ID Pairs

8-22

8.15

Copying a Data Item Passed by Name

8-24

8.16

Deleting the Last Item Placed on the Clipboard

8-25

8.17

8-26

8-18
.............................. .

8-19

.......................................... .

8-20

.................................... .
....................................... .

Compound String Functions

9.1

Creating a Font List and Font List Entries

9.2

Creating a Compound String

9.3

Comparing and Manipulating Compound Strings
9.3.1
9.3.2
9.3.3
9.3.4
9.3.5
9.3.6

.. ... . .. ... . .. ... ....... . . . .. .... .. .

9-1

.......................................................

9-2

...........................

9-4

Determining If Two Compound Strings Are Identical
Determining If a Compound String Is Empty ..................... .
Appending a Copy of a String to Another String ................ .
Copying a String to the Output String .............................. .
Returning the Number of Bytes in String1 ....................... ..
Working with Segments ................................................. .

9-4
9-5
9-5
9-6
9-6
9-7

9.4

Freeing a Compound String Context Structure

Convenience Functions

10.1

Functions That Display Messages

10.3

9-9

..............................................

10-1

Accepting and Displaying a VMS Message ......................
Displaying a Compound String Message ..........................

10-2
10-3

Function That Allows Writing Upward-Compatible Applications
and Widgets .........................................................................

10-5

Function That Allows Applications to Simulate Push Button
Activation ...........................................................................

10-6

10.1.1
10.1.2
10.2

8-21

xii Contents

10.4

Function That Returns User Data Associated with the Widget

10-7

Widget Attributes

A.1

Attached Dialog Box and Attached Dialog Box Pop-Up Widgets

A-I

A.2

Caution Box Widget

A-4

A.3

Color Mix Widget

A-7

A.4

Command Window Widget

A.5

Compound String Text Widget

A.6

Dialog Box and Pop-Up Dialog Box Widgets

A.7

File Selection Widget

A.8

Help Widget

A.9

Label Widget

A-22

A.10

Label Gadget

A-24

A.II

List Box Widget

A-25

A.I2

Main Window Widget

A-27

A.I3

Menu Bar Widget

A-28

A.I4

Menu, Pull-Down Menu, and Pop-Up Menu Widgets

A.I5

Message Box Widget

A-35

A.I6

Option Menu Widget

A-37

A.I7

Pull-Down Menu Entry Widget

A-39

A.I8

Pull-Down Menu Entry Gadget

A.19

Push Button Widget

A.20

Push Button Gadget

A.21

Radio Box Widget

................................................................. .

A-40
A-42
A-44
A-45

A.22

Scale Widget

......................................................................... .

A-46

A.23

Scroll Bar Widget

A.24

Scroll Window Widget

....................................................... .
.................................................. .

A-II
A-I3

.............................. .

A-I5

............................................................... .

A-I7

........................................................................... .

A-20

.................................................................. .
................. .

.................................................................. .

A-30

A-48
A-50

Contents xiii

A.25

Selection Widget

A-51

A.26

Separator Widget

A-54

A.27

Separator Gadget

A-55

A.28

Simple Text Widget

A-56

A.29

Toggle Button Widget

A-58

A.30

Toggle Button Gadget

A-60

A.31

Window Widget

A-61

A.32

Work-in-Progress Box Widget

A-63

Figures
1-1: Widget Class Hierarchy

1-4

Tables
1-1: Core Widget and Common Widget Attributes
1-2: Callback Structure Names

................................

1-5

............................................................

1-10

2-1: Attributes Inherited by the Main Window Widget

...........................

2-2: Widget-Specific Attributes for the Main Window Widget

................

2-3: Attributes Inherited by the Menu Bar Widget
2-4: Attributes Inherited by the Window Widget

2-6
2-7
2-11

...................................

2-15

2-5: Widget-Specific Attributes for the Window Widget

.........................

2-17

2-6: Attributes Inherited by the Scroll Window Widget

..........................

2-19

2-7: Widget-Specific Attributes for the Scroll Window Widget
3-1: Attributes Inherited by the Scroll Bar Widget

........ .......

2-20

.................................

3-7

3-2: Widget-Specific Attributes for the Scroll Bar Widget
3-3: Attributes Inherited by the Label Widget

......................

3-8

.......................................

3-15

3-4: Widget-Specific Attributes for the Label Widget

.............................

3-16

3-5: Attributes Inherited by the Toggle Button Widget

...........................

3-21

xiv Contents

3-6: Widget-Specific Attributes for the Toggle Button Widget

................

3-23

3-7: Attributes Inherited by the Radio Box Widget

................................

3-28

3-8: Attributes Inherited by the Push Button Widget

..............................

3-33

...................

3-35

......................................

3-41

3-9: Widget-Specific Attributes for the Push Button Widget
3-10: Attributes Inherited by the Scale Widget

3-11: Widget-Specific Attributes for the Scale Widget

...........................

3-42

.......................................

4-7

4-2: Attributes Inherited by the Pull-Down Menu and Pop-Up Menu
Widgets ...............................................................................

4-8

4-3: Widget-Specific Attributes for the Menu Widget

4-10

4-1: Attributes Inherited by the Menu Widget

4-4:
Pull-Down Menu and Pop-Up Menu Widgets ...........................

4-15

4-5: Attributes Inherited by the Pull-Down Menu Entry Widget

4-18

4-6: Widget-Specific Attributes for the Pull-Down Menu Entry Widget....

4-20

4-7: Attributes Inherited by the Option Menu Widget

4-23

............................

4-8: Widget-Specific Attributes for the Option Menu Widget

4-25

4-9: Attributes Inherited by the Separator Widget

4-28

..................................

4-10: Widget-Specific Attribute for the Separator Widget

.......................

4-30

5-1: Attributes Inherited by the Dialog Box and Pop-Up Dialog Box
Widgets .............................. .................................................

5-7

5-2: Widget-Specific Attributes for the Dialog Box and Pop-Up Dialog
Box Widgets ........................................................................

5-8

5-3: Widget-Specific Attributes for the Pop-Up Dialog Box Widget

.........

5-9

5-4: Attributes Inherited by the Attached Dialog Box and Attached Dialog
Box Pop-Up Widgets ............................................................

5-18

5-5: Widget-Specific Attributes for the Attached Dialog Box and Attached
Dialog Box Pop-Up Widgets ..................................................

5-21

5-6: Attributes Inherited by the Simple Text Widget

5-29

..............................

5-7: Widget-Specific Attributes for the Simple Text Widget

...................

5-8: Attributes Inherited by the Compound String Text Widget

...............

5-30
5-40

Contents xv

5-9: Widget-Specific Attributes for the Compound String Text Widget

5-41

5-10: Attributes Inherited by the Color Mix Widget

5-52

...............................

5-11: Widget-Specific Attributes for the Color Mix Widget

5-54

5-12: Attributes Inherited by the List Box Widget

5-65

.. ... ... ... . .. . .. .. .. .. . .. . .. . .. .

5-13: Widget-Specific Attributes for the List Box Widget
6-1: Attributes Inherited by the Help Widget

.......................

5-66

........................................

6-5

6-2: Widget-Specific Attributes for the Help Widget

..............................

6-3: Attributes Inherited by the Work-in-Progress Box Widget

................

6-6
6-15

6-4: Widget-Specific Attributes for the Work-in-Progress Box Widget

6-16

6-5: Attributes Inherited by the Message Box Widget

6-20

............................

6-6: Widget-Specific Attributes for the Message Box Widget
6-7: Attributes Inherited by the Caution Box Widget

..................

6-22

.............................

6-27

6-8: Widget-Specific Attributes for the Caution Box Widget

...................

6-28

6-9: Attributes Inherited by the Command Window Widget

....................

6-32

6-10: Widget-Specific Attributes for the Command Window Widget
6-11: Attributes Inherited by the Selection Box Widget

........

6-34

. . .. .. . . . . . . . . .. . .. .. . . .. .

6-40
6-42

6-12: Widget-Specific Attributes for the Selection Box Widget
6-13: Attributes Inherited by the File Selection Box Widget

...................

6-14: Widget-Specific Attributes for the File Selection Box Widget
7 -1: Gadget Classes and Parents

6-47

.........

6-49

. .. . .. . .. . . .. .. . ... .. ... . .. . .. ... . .... . . . . . . . . .. . .. .. . . .. .

7-1

7-2: Attributes Inherited by the Label Gadget

.......................................

7-3: Widget-Specific Attributes for DwtLabelGadgetCreate
7-4: Attributes Inherited by the Push Button Gadget

7-5

....................

7-5

..............................

7-7

7-5: Widget-Specific Attributes for the Push Button Gadget

....................

7-8

7 -6: Attributes Inherited by the Separator Gadget

7-10

7-7: Widget-Specific Attribute for the Separator Gadget

7-10

7-8: Attributes Inherited by the Toggle Button Gadget

7-13

7-9: Widget-Specific Attributes for the Toggle Button Gadget

xvi Contents

.................

7-13

7-10: Attributes Inherited by the Pull-Down Menu Entry Gadget

............ .

7-16

7-11: Widget-Specific Attributes for the Pull-Down Menu Entry Gadget

7-17

8-1: Data Format Names

8-3

A-I: Attributes Inherited by the Attached Dialog Box and Attached Dialog
Box Pop-Up Widgets ........................................................... .

A-I

A-2: Widget-Specific Attributes for the Attached Dialog Box and Attached
Dialog Box Pop-Up Widgets ............................................... .

A-4

A-3: Attributes Inherited by the Caution Box Widget

A-5

A-4: Widget-Specific Attributes for the Caution Box Widget
A-5: Attributes Inherited by the Color Mix Widget

................. .

A-6

............................... .

A-7

A-6: Widget-Specific Attributes for the Color Mix Widget

A-8

A-7: Attributes Inherited by the Command Window Widget

...................

A-8: Widget-Specific Attributes for the Command Window Widget
A-9: Attributes Inherited by the Compound String Text Widget

A-II

.........

A-12

..............

A-13

A-I0: Widget-Specific Attributes for the Compound String Text Widget

A-14

A-II: Attributes Inherited by the Dialog Box and Pop-Up Dialog Box
Widgets ...............................................................................

A-15

A-12: Widget-Specific Attributes for the Dialog Box and Pop-Up Dialog
Box Widgets ........................................................................

A-15

A-13: Widget-Specific Attributes for the Pop-Up Dialog Box Widget

A-16

A-14: Attributes Inherited by the File Selection Widget

A-17

.........................

A-15: Widget-Specific Attributes for the File Selection Widget
A-16: Attributes Inherited by the Help Widget

...............

A-19

......................................

A-20

A-17: Widget-Specific Attributes for the Help Widget
A-18: Attributes Inherited by the Label Widget

...........................

A-21

.....................................

A-23

A-19: Widget-Specific Attributes for the Label Widget

A-24

A-20: Attributes Inherited by the Label Gadget

A-24

.....................................

A-21: Widget-Specific Attributes for the the Label Gadget
A-22: Attributes Inherited by the List Box Widget

.....................

A-25
A-25

Contents xvii

A-23: Widget-Specific Attributes for the ListBox Widget

......................

A-26

A-24: Attributes Inherited by the Main Window Widget

A-27

A-25: Widget-Specific Attributes for the Main Window Widget

A-28

A-26: Attributes Inherited by the Menu Bar Widget

..............................

A-28

....................................

A-30

A-28: Attributes Inherited by the Pull-Down Menu and Pop-Up Menu
Widgets ...............................................................................

A-32

A-29: Widget-Specific Attributes for the Pull-Down Menu and Pop-Up
Menu Widgets ......................................................................

A-34

A-30: Widget-Specific Attributes for the Menu Widget

..........................

A-34

A-31: Attributes Inherited by the Message Box Widget

..........................

A-35

A-27: Attributes Inherited by the Menu Widget

A-32: Widget-Specific Attributes for the Message Box Widget
A-33: Attributes Inherited by the Option Menu Widget

...............

A-36

..........................

A-37

A-34: Widget-Specific Attributes for the Option Menu Widget

...............

A-38

A-35: Attributes Inherited by the Pull Down Menu Entry Widget

............

A-39

A-36: Widget-Specific Attributes for the Pull Down Menu Entry Widget

A-40

A-37: Attributes Inherited by the Pull-Down Menu Entry Gadget

A-41

A-38: Widget-Specific Attributes for the the Pull-Down Menu Entry
Gadget ................................................................................

A-41

A-39: Attributes Inherited by the Push Button Widget

A-42

A-40: Widget-Specific Attributes for the Push Button Widget
A-41: Attributes Inherited by the Push Button Gadget

.................

A-43

............................

A-44

A-42: Widget-Specific Attributes for the the Push Button Gadget

............

A-44

A-43: Attributes Inherited by the Radio Box Widget

A-45

A-44: Attributes Inherited by the Scale Widget

A-47

A-45: Widget-Specific Attributes for the Scale Widget

...........................

A-48

A-46: Attributes Inherited by the Scroll Bar Widget

..............................

A-48

A-47: Widget-Specific Attributes for the Scroll Bar Widget

....................

A-49

A-48: Attributes Inherited by the Scroll Window Widget

.......................

A-50

xviii Contents

A-49: Widget-Specific Attributes for the Scroll Window Widget
A-50: Attributes Inherited by the Selection Widget

.............

A-51

................................

A-51

A-51: Widget-Specific Attributes for the Selection Widget

A-53

A-52: Attributes Inherited by the Separator Widget

A-54

...............................

A-53: Widget-Specific Attributes for the Separator Widget
A-54: Attributes Inherited by the Separator Gadget

.....................

A-55

................................

A-55

A-55: Widget-Specific Attributes for the the Separator Gadget
A-56: Attributes Inherited by the Simple Text Widget

................

A-56

...........................

A-56

A-57: Widget-Specific Attributes for the Simple Text Widget

A-57

A-58: Attributes Inherited by the Toggle Button Widget

A-58

A-59: Widget-Specific Attributes for the Toggle Button Widget
A-60: Attributes Inherited by the Toggle Button Gadget

..............

A-59

.........................

A-60

A-61: Widget-Specific Attributes for the the Toggle Button Gadget
A-62: Attributes Inherited by the Window Widget

.........

A-61

.................................

A-61

A-63: Widget-Specific Attributes for the Window Widget

......................

A-64: Attributes Inherited by the Work-in-Progress Box Widget
A-65: Widget-Specific Attributes for the Work-in-Progress Box Widget

A-62
A-63

...

A-64

Contents xix

About This Manual

This manual describes the library of high-level and low-level C functions you use to
write user interface application programs that adhere to the look and feel of the X
User Interface (XVI). In addition, this manual describes other toolkit functions that
you might find useful when writing your applications.

Audience
The audience for this manual includes:
•

Application programmers

•

Widget programmers

•

Software support representatives (Digital only)

•

Course instructors (Digital only)

Organization
Summary of Technical Changes
Summarizes the changes in this manual for ULTRIX Worksystem
Software (UWS) Version 2.2.
Part One: Introduction
Chapter I

Programming Considerations
Discusses the issues you need to consider when using the XVI
widget functions.

Part Two: Widget Functions
Chapter 2

Window Widget Functions
Describes the components of a main window. Also discusses the
functions that allow you to create instances of these widgets: main
window, menu bar, window, and scroll window. In addition,
describes how to add subwidget instances to the main window and
scroll window widgets.

Chapter 3

Subarea Widget Functions

Discusses the functions that allow you to create instances of these
widgets: scroll bar, toggle button, push button, and scale. In
addition, this chapter describes convenience functions for obtaining
and setting the scroll bar slider position, toggle button state, and
scale slider position.
Chapter 4

Menu Widget Functions
Discusses the functions that allow you to create instances of these
widgets: pull-down menu, pop-up menu, pull-down menu entry,
option menu, and separator.

Chapter 5

Dialog Box and Text Widget Functions
Discusses the functions that allow you to create instances of these
widgets: dialog box, pop-up dialog box, attached dialog box,
pop-up attached dialog box, simple text, compound string text,
color mix, and list box. In addition, this chapter describes
convenience functions for manipulating the simple text widget, the
compound string text widget, the color mix widget, and the list
box widget.

Chapter 6

Standard Menus and Dialog Box Widget Functions
Discusses the functions that allow you to create instances of these
widgets: help menu, work-in-progress box, message box, caution
box, command window, selection box, and file selection box.

Chapter 7

Gadget Functions
Discusses the gadget functions, which are reduced functionality
widgets.

Part Three: Other Toolkit Functions
Chapter 8

Cut and Paste Functions
Discusses functions that allow you to perform cut and paste
operations.

Chapter 9

Compound String Functions
Discusses the functions you use to create and manipulate
compound strings.

Chapter 10

Convenience Functions
Discusses the functions you use to display VMS messages and
compound string messages. In addition, discusses a function that
allows you to write upward compatible applications and widgets.

Appendix A

Widget Attributes
Provides tables that list attributes supported by each widget.

xxii About This Manual

Related Documentation
XUI Style Guide
Describes the standard user interface for XUI Toolkit applications, and defines
the appearance, behavior, and usage of the user interface components.
XUI Programming Overview
Describes the low-level and high-level components and libraries of the X
window system.
Guide to Writing Applications Using XUI Toolkit Widgets
Describes how to write applications using the XUI Toolkit.
Guide to the XUI User Interface Language Compiler
Describes the XUI User Interface Language CUIL) and its compiler.
Guide to the XUI Toolkit Intrinsics: C Language Binding
Describes the library of X intrinsics C functions used to build and manipulate
widgets.
Guide to the Xlib Library: C Language Binding
Describes the library of low-level C language functions to the X Window
System protocol.

Conventions
The following conventions are used in this manual:
cat(1)

Cross-references to the ULTRIX Reference Pages include the
appropriate section number in parentheses. For example, a
reference to cat(1) indicates that you can find the material on
the cat command in Section 1 of the reference pages.

system output This typeface is used in interactive examples to indicate system
output, and also in code examples and other screen displays. In
text, this typeface is used to indicate the exact name of a
command, option, partition, pathname, directory, or file.

filename

In syntax descriptions and function definitions, italics are used to
indicate variable values; and in text, to introduce new terms or
give references to other documents.

About This Manual xxiii

A vertical ellipsis indicates that a portion of an example that
would normally be present is not shown.

mouse

The term mouse is used to refer to any pointing device, such as a
mouse, a puck, or a stylus.

MBl, MB2, MB3 MBI indicates the left mouse button, MB2 indicates the middle
mouse button, and MB3 indicates the right mouse button. (The
buttons can be redefined by the user.)

xxiv About This Manual

Summary of Technical Changes

This section describes the technical changes in this manual for ULTRIX W orksystem
Software (UWS) Version 2.2. These technical changes also appear in the appropriate
sections of the manual. The changes fall into these categories:
•

Additions and changes to high-level widget and widget convenience functions

•

Additions and changes to low-level widget functions

•

Additions and changes to cut and paste functions

•

Additions and changes to compound string functions

•

New convenience functions

The manual also includes an appendix that lists the attributes for all widgets.

Additions and Changes to High-Level Widget and Widget
Convenience Functions
This section describes new high-level widget and widget convenience functions, and
also describes changes made to existing functions.

New High-Level Widget and Widget Convenience Functions
The following table lists the new high-level widget and high-level widget
convenience functions. All these functions are described in Chapter 5.
Function

Summary Description

DwtCSText
DwtCSTextClearSelection

Creates a compound-string text widget.
Clears the global selection highlighted
in the compound-string text widget.
Obtains the current edit permission
state indicating whether the user can
edit the text in the compound-string
text widget.
Obtains the current maximum
allowable length of the text in the
compound-string text widget.

DwtCSTextGetEdi table

DwtCSTextGetMaxLength

Function

Summary Description

DwtCSTextGetSelection

Retrieves the global selection, if any,
currently highlighted, in the compound
string text widget.
Retrieves all text from the compoundstring text widget.
Replaces a portion of the current text
in the compound-string text widget or
inserts some new text into the current
text of the compound-string text
widget.
Sets the permission state that
determines whether the user can edit
text in the compound-string text
widget.
Sets the maximum allowable length of
the text in the compound-string text
widget.
Highlights the specified text in the
compound-string text widget and
makes it the current global selection.
Changes the text in the compoundstring text widget.
Returns the red, green, and blue color
values to the color mixing widget.
Sets the new red, green, and blue color
values in the color mixing widget.

DwtCSTextGetString
DwtCSTextReplace

DwtCSTextSetEditable

DwtCSTextSetMaxLength

DwtCSTextSetSelection

DwtCSTextSetString
DwtColorMixGetNewColor
DwtColorMixSetNewColor

Changes to High-Level Functions
Changes were made to the following high-level functions:
•

DwtDialogBox

•

DwtListBoxltemExists

•

DwtMenu

•

DwtOptionMenu

•

DwtScale

Changes to DwtDialogBox
The description for the map_callback argument has changed to the following:
map_callback Specifies the callback function or functions called when the window
is about to be mapped. For this callback, the reason is DwtCRMap.

xxvi Summary of Technical Changes

Note that map_callback is supported only if style is DwtModal or
DwtModeless. If style is DwtWorkarea, map_callback is
ignored.
This argument sets the DwtNmapCallback attribute associated
with DwtDialogBoxPopupCreate.
Changes to DwtListBoxltemExists - The DwtListBoxItemExists
function no longer returns a Boolean value. The following description describes
what DwtListBoxItemExists returns:

The DwtListBoxItemExists function searches through a list box to determine
if an item exists. If the specified item is found, DwtListBoxItemExists
returns an integer that gives the position of the item in the list box. If the item is not
found, DwtListBoxItemExists returns a zero.
Changes to DwtMenu - The description for the map_callback argument has
changed as follows:
map_callback Specifies the callback function or functions called when the window
is about to be mapped. For this callback, the reason is DwtCRMap.
The map_callback argument is supported only if format is
DwtMenuPopup or DwtMenuPulldown. The map callback
argument is ignored ifformat is DwtMenuWorkArea-:

This argument sets the DwtNmapCallback attribute associated
with DwtMenuCreate.
Changes to DwtOptionMenu - The DwtOptionMenu function now supports
the sub_menu_id argument:
sub menu id

Specifies the widget ID of the pull-down menu associated with the
option menu during the creation phase.

Changes to DwtScale - The description for the min_value argument has changed
as follows:
min value

Specifies the value represented by the top or left end of the scale.
This argument sets the DwtNminValue attribute associated with
DwtScaleCreate.

The description for the max_value argument has changed as follows:
max value

Specifies the value represented by the bottom or right end of the
scale. This argument sets the DwtNmaxVal ue attribute associated
with DwtScaleCreate.

Summary of Technical Changes xxvii

Additions and Changes to Low-Level Widget Functions
This section describes new low-level widget functions, and also describes changes
made to existing functions.

New Low-Level Widget Functions
The following table lists the new low-level widget functions. The
DwtColorMixCreate and DwtCSTextCreate functions are described in
Chapter 5. The DwtPullEntryGadgetCreate function is described in Chapter

7.
Function

Summary Description

DwtColorMixCreate

Creates a color mixing widget, which
is a pop-up dialog box containing a
default color display subwidget and a
default color mixer subwidget.
Creates a compound-string text widget.
Creates a pull-down menu entry
gadget.

DwtCSTextCreate
DwtPullEntryGadgetCreate

Changes to Low-Level Functions
Changes were made to the following low-level functions:
•

DwtAttachedDBCreate

•

The DwtNdestroyCallback core and the DwtNdirectionRToL
common attributes

•

DwtDialogBoxCreate

•

DwtDialogBoxPopupCreate

•

DwtFileSelectionCreate

•

DwtHelpCreate

•

DwtMenuCreate, DwtMenuBarCreate, DwtOptionMenuCreate,and
DwtRadioBoxCreate

•

DwtMenuPopupCreate and DwtMenuPulldownCreate

•

DwtMessageBoxCreate

•

DwtPushButtonCreate

•

DwtSTextCreate

xxviii Summary of Technical Changes

•

DwtScaleCreate

•

DwtScrollBarCreate

•

DwtToggleButtonCreate

Changes to DwtAttachedDBCreate - The DwtAttachedDBCreate function
now supports the DwtNresizable constraint attribute:
Attribute Name

Data Type

Default

DwtNresizable

Boolean

True

DwtNresizable

Specifies a boolean value that, when True, indicates that
the attached dialog box can change the size of the child
widget. If False, indicates that the attached dialog box
cannot change the size of the child widget.

Changes to the DwtNdestroyCaliback and DwtNdirectionRToL Attributes
- The DwtNdestroyCallback core and DwtNdirectionRToL common
attributes are now described as follows:
Attribute Name

Data Type

Default

DwtNdestroyCallback
DwtNdirectionRToL

DwtCallbackPtr
unsigned char

NULL
DwtDirectionRightDown

DwtNdestroyCallback
Specifies the callback function or functions called when the
widget is about to be destroyed. Unlike all other toolkit
callbacks, DwtNdestroyCallback returns only two
valid arguments: widget_id and tag. The callback_data
argument is NULL. Therefore, applications should avoid
setting DwtNdestroyCallback to call general callback
functions (for example, functions to handle activate, arm,
disarm, and similar actions), because these functions depend
on the caUback_data argument.
DwtNdirectionRToLSpecifies the direction in which the text is drawn and wraps.
You can pass DwtDirectionLeftDown (text is drawn
from left to right and wraps down);
DwtDirectionRightUp (text is drawn from left to right

Summary of Technical Changes xxix

and wraps up); DwtDirectionLeftDown (text is drawn
from right to left and wraps down); or
DwtDirectionLeftUp (text is drawn from right to left
and wraps up).
Changes to DwtDialogBoxCreate - The DwtNdirectionRToL widgetspecific attribute is now described as follows:
Attribute Name

Data Type

Default

DwtNdirectionRToL

unsigned char

DwtDirectionRightDown

DwtNdirectionRToLSpecifies the direction in which the text is drawn and wraps.
You can pass DwtDirectionLeftDown (text is drawn
from left to right and wraps down);
DwtDirectionRightUp (text is drawn from left to right
and wraps up); DwtDirectionLeftDown (text is drawn
from right to left and wraps down); or
DwtDirectionLeftUp (text is drawn from right to left
and wraps up).
Changes to DwtDialogBoxPopupCreate - The
DwtDialogBoxPopupCreate function now supports the
DwtNautoUnrealize attribute. In addition, the description for the
DwtNdefaultPosition attribute has changed:
Attribute Name

Data Type

Default

DwtNautoUnrealize
DwtNdefaultPosition

Boolean
Boolean

False
False

DwtNautoUnrealizeSpecifies a boolean value that, when False, indicates that
the dialog box creates the window(s) for itself and its
children when it is first managed, and never destroys them.
If True, the dialog box re-creates the window(s) every time
it is managed, and destroys them when it is unmanaged.
The setting of this attribute is a performance tradeoff between
the client cpu load (highest when set to True), and the
server window load (highest when set to False).

xxx Summary of Technical Changes

DwtNdefaultPosition
Specifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. If False, the specified DwtNx and
DwtNy attributes are used to position the widget.

If the dialog box is displayed partially off the screen as a
result of being centered in the parent window, the centering
rule is violated. When this occurs, the parent window is
repositioned so that the entire dialog box is displayed on the
screen.

The pop-up dialog box is recentered every time it is popped
up. Consequently, if the parent moves in between
invocations of the dialog box, the box pops up centered in
the parent window's new location. However, the dialog box
does not dynamically follow its parent while it is displayed.
If the parent is moved, the dialog box will not move until the
next time it is popped up.
If the user moves the dialog box with the window manager,
the toolkit turns off DwtNdefaultPosition. This
results in the dialog box popping up in the location specified
by the user on each subsequent invocation.

The description for DwtDialogBoxPopupCreate has changed to include
information on the setting of colormaps. The information in the second paragraph
relates to setting the colormap of a pop-up dialog box. For convenience, the entire
dialog box description is included here:
Depending on the constant you pass to DwtNstyle, the DwtDialogBox
function creates a dialog box or a pop-up dialog box widget. The
DwtDialogBoxCreate function creates a dialog box widget, and
DwtDialogBoxPopupCrea1;:e creates a pop-up dialog box widget. Upon
completion, these functions return the associated widget ID. When calling
DwtDialogBox, you set the dialog box widget attributes presented in the formal
parameter list. For DwtDialogBoxCreate and
DwtDialogBoxPopupCreate, however, you specify a list of attribute
name/value pairs that represent all the possible dialog box widget attributes.
The dialog box widget is a composite widget that contains other subwidgets. Each
subwidget displays information or requests and/or handles input from the user.
The dialog box widget functions as a container only, and provides no input semantics
over and above the expressions of the widgets it contains.
Subwidgets can be positioned within the dialog box in two ways: by font units and
by pixel units. By default, subwidgets are positioned in terms of font units (that is,
DwtNunits is DwtFontUnits). The X font units are defined to be one-fourth

Summary of Technical Changes xxxi

the width of whatever font is supplied for the common attribute DwtNfont. The Y
font units are defined to be one-eighth the width of whatever font is supplied for
DwtNfont. (Width is taken from the QUAD_WIDTH property of the font.)
Subwidgets can also be positioned in terms of pixel units (that is, DwtNuni ts is
DwtP ixelUni ts).
Note that when changing DwtNtextMergeTranslations, the existing widgets
are not affected. The new value for DwtNtextMergeTranslations acts only
on widgets that are added after the pop-up dialog box is created.
Changes to DwtFileSelectionCreate - The DwtFileSelectionCreate
function has the following new attributes:
Attribute Name

Data Type

Default

DwtNfileToExternProc
DwtNfileTolnternProc
DwtNmaskToExternProc
DwtNmaskTolnternProc

VoidProc
VoidProc
VoidProc
VoidProc

NULL
NULL
NULL
NULL

DwtNfileToExternProc
Converts native, internal file names to custom, external file
names displayed to the user.
DwtNfileToInternProc
Converts custom, external file names displayed to the user to
native, internal file names.
DwtNmaskToExternProc
Converts native, internal directory masks to custom, external
directory masks displayed to the user.
DwtNmaskToInternProc
Converts custom, external directory masks displayed to the
user to native, internal directory masks.

Changes to DwtHelpCreate - The DwtHelpCreate function no longer
supports these attributes:
•

DwtNhelpmessageTitle

•

DwtNhelpmessageTitleType

•

DwtNnulltopicMessage

xxxii Summary of Technical Changes

The following attributes have new default values:
Attribute Name

Data Type

Default

DwtNaddtopicLabel
DwtNbadframeMessage
DwtNbadlibMessage
DwtNerroropenMessage
DwtNfirstTopic
DwtNhelpFont

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtFontList

DwtNhelpLabel
DwtNhistoryboxLabel
DwtNkeywordsLabel
DwtNnokeywordMessage
DwtNnotitleMessage
DwtNtitlesLabel
DwtNtopictitlesLabel

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString

" Additional topics"
"Couldn't find frame !CS"
"Couldn't open library !CS"
"Error opening file !CS"
NULL
Language-dependent. The
American English default is "*-TERMINAL-MEDIUM-RNARROW--*-140*-*-C-*-IS08859-1"
"Using Help"
"Search Topic History"
"Keyword"
"Couldn't find keyword !CS"
"No title to match string !CS"
"Title"
"Topic Titles "

The following attributes for DwtHelpCreate are now described as follows:
DwtNgobackLabel Specifies the text for a label used on the pull-down menu

under View. Clicking on this object returns the user to the
previous topic displayed.
DwtNgotoLabel

Specifies the text for the label used on a push button in the
help widget's dialog boxes. Clicking on this object after
selecting a new topic displays help on the new topic in the
same Help window.

DwtNvisitLabel

Specifies the text for an entry on a push button in a help
widget's dialog boxes. Clicking on this object causes
information on a new topic to be displayed in a new window.

The DwtHelpCreate function now supports the following new attributes:
Attribute Name

Data Type

Default

DwtNcacheHelpLibrary
DwtNcloseLabel
DwtNgobacktopicLabel
DwtNgototopicLabel
DwtNhelpAcknowledgeLabel

Boolean
DwtCompString
DwtCompString
DwtCompString
DwtCompString

False
"Exit"
"Go Back"
"Go To Topic"
"Acknowledge"

Summary of Technical Changes xxxiii

Attribute Name

Data Type

Default

DwtNhelphelpLabel
DwtNhelpOnHelpTitle
DwtNhelpontitleLabel
DwtNhelptitleLabel
DwtNmapCallback
DwtNvisittopicLabel

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCompString

"Overview"
"Using Help"
"Help on "
"Help"
NULL
"Visit Topic"

DwtNcacheHelpLibrary
Specifies a boolean value that, when True, indicates that
the text is stored in cache memory. If False, the text is
not stored in cache memory.
DwtNcloseLabel Specifies the label for the Exit push button in the help widget
window.
DwtNgobacktopicLabel
Specifies the label for the Go Back push button in the help
widget window.
DwtNgototopicLabel
Specifies the label for the Go To Topic menu entry in the
View pull-down menu.
DwtNhelpAcknowledgeLabel
Specifies the label for the Acknowledge push button in the
error message box.
DwtNhelphelpLabelSpecifies the label for the Overview menu item in the Using
Help pull-down menu.
DwtNhelpOnHelpTitle
Specifies the label for the title bar in the Help-on-Help help
widget.
DwtNhelpontitleLabel
Specifies the label for the help widget title bar used in
conjunction with the application name.
DwtNhelptitleLabel
Specifies the label for the help widget title bar when no
application name is specified.
DwtNrnapCallback Specifies the callback function or functions called when the
help widget is about to be mapped.
DwtNvisittopicLabel
Specifies the label for the Visit Topic menu entry in the
View pull-down menu.

xxxiv Summary of Technical Changes

Changes to DwtMenuCreate, DwtMenuBarCreate, DwtOptionMenuCreate,
and DwtRadioBoxCreate - The DwtMenuCreate function (because it creates a
work area menu) does not support the DwtNmapCallback and
DwtNunmapCallback attributes; therefore, they have been deleted from the table
of widget-specific attributes. In addition, these attributes have been removed from
the table of inherited attributes for DwtMenuBarCreate,
DwtOptionMenuCreate,and DwtRadioBoxCreate.
The DwtMenuCreate function now supports these attributes:
Attribute Name

Data Type

Default

DwtNchangeVisAtts
DwtNmenuExtendLastRow

Boolean
Boolean

True
True

DwtNchangeVisAttsSpecifies a boolean value that, when True, indicates that a
menu widget can optionally make these changes to its
children: (1) Set the border to a uniform widget; (2) align
labels; (3) make margins for the border highlight at least 2
pixels wide; (4) set the indicator shape to oval for toggle
buttons in radio boxes; (5) set DwtNvisibleWhenOff to
F al s e for toggle buttons.
When DwtNchangeVisAtts is False, a menu widget
cannot make any of these changes.
DwtNmenuExtendLastRow
Specifies the boolean value that indicates whether the active
area of each menu entry extends to the width of the menu
(for vertical menus) or the height of the menu (for horizontal
menus).
If True for vertical menus, all menu entries extend to the
menu width; if False, menu entries vary in length
depending on the length of the label in the menu entry. If
True for horizontal menus, all menu entries extend to the
menu height; if F al s e, menu entries vary in height,
depending on the length of the label in the menu entry.

Changes to DwtMenuPopupCreate and DwtMenuPulidownCreate - The
DwtMenuPopupCreate and DwtMenuPulldownCreate functions now
support these additional attributes:
Attribute Name

Data Type

Default

DwtNmapCallback
DwtNunmapCallback

DwtCallbackptr
DwtCallbackPtr

NULL
NULL

Summary of Technical Changes xxxv

DwtNmapCallback Specifies the callback function or functions called when the
menu is mapped.
DwtNunmapCallbackSpecifies the callback function or functions called when the
menu is unmapped.
Changes to DwtMessageBoxCreate - The DwtMessageBoxCreate
function now supports these attributes:
Attribute Name

Data Type

Default

DwtNsecondLabel
DwtNlabelAlignment
DwtNsecondLabelAlignment
DwtNiconPixmap

DwtCompString
unsigned char
unsigned char
P ixmap

NULL
DwtAlignmentCenter
DwtAlignmentBeginning
The default is the standard icon
provided for each message-class
widget as follows: (1) the default
caution box icon is an
exclamation point; (2) the default
message box icon is an asterisk;
(3) the default work box icon is
the wait cursor (watch). See the
XUI Style Guide for illustrations
of the icons for each message
class widget.

DwtNsecondLabel Specifies the text for the secondary label. If the application
specifies a second label and then wants to remove it, it
should use XtSetValues to set DwtNsecondLabel to
NULL or to an empty compound-string.
DwtNlabelAlignment
Specifies the alignment for the primary label. You can pass
DwtAlignmentCenter (center alignment),
DwtAlignmentBeginning (alignment at the beginning),
or DwtAlignmentEnd (alignment at the end).
DwtNsecondLabelAlignment
Specifies the alignment for the secondary label. You can
pass DwtAlignmentCenter (center alignment),

xxxvi Summary of Technical Changes

DwtAlignmentBeginning (alignment at the beginning),
or DwtAlignmentEnd (alignment at the end).
DwtNiconP ixmap

Specifies the pixmap used for the icon.

The information in the following paragraph contains changes to the description of the
DwtMessageBoxCreate function. Specifically, the changes are contained in the
second paragraph, but for your convenience, the entire description is included here:
The DwtMessageBox and DwtMessageBoxCreate functions create an
instance of the message box widget and return its associated widget ID. When
calling DwtMe s s ageBox, you set the message box attributes presented in the
formal parameter list. For DwtMessageBoxCreate, however, you specify a list
of attribute name/value pairs that represent all the possible message box widget
attributes.
The DwtMessageBoxCreate function conforms to the XUI Style Guide by
providing optional secondary text below the primary text. This function also
supports alignment mode for both the DwtNlabelAlignment and
DwtNsecondLabelAlignment attributes.
The message box widget is a dialog box that allows the application to display
informational messages to the user. You call this function to create a message box
when the user does something unexpected, or when your application needs to display
information to the user. The message box widget may contain an OK push button.
When the style is DwtModal, the message box freezes the application and requires
the user to explicitly dismiss the message box before the application proceeds. If the
style is DwtModal when the user selects the OK push button, the widget is cleared
from the screen but not destroyed. You can redisplay the widget by calling
XtManageChild.

Changes to DwtPushButtonCreate - The DwtPushButtonCreate function
now supports this attribute:
Attribute Name

Data Type

Default

DwtNinsensitivePixmap

Pixmap

NULL

DwtNinsensitivePixmap

Specifies the pixmap used when the push button is set to
insensitive. This attribute applies only if the push button
label is specified as a pixmap.

Summary of Technical Changes xxxvii

Changes to DwtSTextCreate - The DwtSTextCreate function now supports
this attribute:
Attribute Name

Data Type

Default

DwtNuserData

Opaque *

NULL

DwtNuserData

Specifies any user private data to be associated with the
widget. The XUI Toolkit does not interpret this data.

Changes to DwtScaleCreate - The DwtScaleCreate function does not
support the DwtNsliderPixmap attribute; therefore, it has been removed from
the table of widget-specific attributes.
Changes to DwtScroliBarCreate - The DwtScrollBarCreate function now
supports this attribute:
Attribute Name

Data Type

Default

DwtNshowArrows

Boolean

True

DwtNshowArrows

Specifies a boolean value that, when True, indicates there
are arrows. If False, there are no arrows.

Changes to DwtToggleButtonCreate - The DwtToggleButtonCreate
function now supports these attributes:
Attribute Name

Data Type

Default

DwtNinsensitivePixmapOn
DwtNinsensitivePixmapOff

Pixmap
Pixmap

NULL
NULL

DwtNinsensitivePixmapOn
Specifies the pixmap used when the toggle button is on and
is insensitive. This attribute applies only if the toggle button
label is specified as a pixmap.
DwtNinsensitivePixmapOff
Specifies the pixmap used when the toggle button is off and
is insensitive. This attribute applies only if the toggle button
label is specified as a pixmap.
xxxviii Summary of Technical Changes

Additions and Changes to Cut and Paste Functions
This section describes new cut and paste functions, and also describes changes made
to existing functions.

New Cut and Paste Functions
Four new cut and paste functions have been added to ensure compliance with the
Inter-Client Communications Conventions Manual (ICCCM). The ICCCM manual
defines conventions for using the global selection mechanism that allows compliant
clients to communicate with each other. The following table lists these new cut and
paste functions, which are described in Chapter 8.
Function

Summary Description

DwtStartCopyToClipboard

Sets up storage and data structures to
receive clipboard data.
DwtStartCopyToClipboardis
identical to
DwtBeginCopyToClipboard,
except that the times tamping of the
event that triggered the copy is
included as an argument. Because it
complies with the ICCCM
conventions, use of
DwtStartCopyToClipboardis
recommended over
DwtBeginCopyToClipboard.
Indicates that the application is ready
to start copying data from the
clipboard and locks the clipboard.
Notifies the cut and paste functions
that the application has completed
copying an item from the clipboard
and unlocks the clipboard.
Registers the length of the data for
formats not specified by ICCCM
conventions.

DwtStartCopyFromClipboard

DwtEndCopyFromClipboard

DwtClipboardRegisterFormat

Changes to Cut and Paste Functions
Changes were made to the following cut and paste functions:

Summary of Technical Changes xxxix

•
•

DwtCopyFromClipboard
DwtlnquireNextPasteCount, DwtlnquireNextPasteFormat,and
DwtlnquireNextPasteLength

Changes to DwtCopyFromClipboard - The following status return values
changed as a result of ICCCM ~ompliance:
ClipboardSuccess

ClipboardTruncate

All data on the clipboard has been copied
successfully. A successful copy can be a
one-time operation using
DwtCopyFromClipboard alone, or an
incremental operation using multiple calls
to DwtCopyFromClipboard between
calls to
DwtStartCopyFromClipboardand
DwtEndCopyFromClipboard.
If using DwtCopyFromClipboard
alone, the data returned is truncated because
the user did not provide a buffer that was
large enough to hold the data. If using
multiple calls to
DwtCopyFromClipboard in between
calls to
DwtStartCopyFromClipboard and
DwtEndCopyFromClipboar~more

data in the requested format remains to be
copied from the clipboard.

Changes to DwtlnquireNextPasteCount, DwtlnquireNextPasteFormat,
and DwtlnquireNextPasteLength - As a result of ICCCM compliance, a new
status return value is possible for DwtlnquireNextPasteCount,
DwtlnquireNextPasteFormat, and DwtlnquireNextPasteLength:
ClipboardNoData

Information could not be obtained from an
application using the ICCCM clipboard
selection mechanism. This return value
indicates that the data was not available in
the requested format.

xl Summary of Technical Changes

Additions and Changes to Compound String Functions
This section describes new compound string functions, and also describes changes
made to existing functions.

New Compound String Functions
The following table lists the new compound string functions, which are described in
Chapter 9.
Function

Summary Description

DwtStringFreeContext

Frees a compound-string context
structure.
Initializes a compound-string context
structure needed by
DwtGetNextSegment

DwtStringIni tContext

Changes to Compound String FuncUons
Changes were made to the following compound string functions:
•

DwtAddFontList, DwtCreateFontList,and DwtGetNextSegment

•

DwtlnitGetSegment

Changes to DwtAddFontList, DwtCreateFontList, and
DwtGetNextSegment - The DwtAddFontList, DwtCreateFontList, and
DwtGetNextSegment functions have the following descripiton for the charset
argument:
charset

Specifies the character set identifier for the font. Values for this
argument can be found in the required file
/usr/include/cda_def.h.

Changes to DwtlnitGetSegment - The information in the following paragraph
contains changes to the description of the Dwtlni tGetSegment function.
Specifically, the changes are contained in the second and third paragraphs, but for
your convenience, the entire description is included here:

degraded from Version 1.0 of the toolkit.

A new function, DwtStringlni tContext, not only provides better
performance, it also creates the context structure that you must allocate separately
when using DwtInitGetSegment. To improve performance, convert calls from
DwtlnitGetSegment to DwtStringlnitContext, and use
DwtStringFreeContext to free the context structure when you are finished with
it.

New Convenience Functions
The following table lists the new convenience functions, which are described in
Chapter 10.
Function

Summary Description

DwtActivateWidget

Allows the application to simulate
push button activation.
Returns the user data associated with
the widget.

DwtGetUserData

xlii Summary of Technical Changes

PART ONE: INTRODUCTION

Programming Considerations

This chapter discusses the following issues you need to consider when using
the C binding with the ULTRIX Worksystem Software XUI Toolkit widget
functions:

1.1

•

Methods for creating widget instances

•

Widget class hierarchy

•

Common attributes

•

Include files

•

The callback mechanism

•

Function format

Methods for Creating Widget Instances
The XUI Toolkit provides three ways to create a widget instance:
•

Low-level functions

•

High-level functions

•

XUI user interface language

Note that creating a widget instance does not cause it to be displayed on the
screen. To display the widget instance on the screen after creating it, call the
X intrinsics function XtRealizeWidget. In fact, there are a number of
X intrinsics functions you can use to manipulate widget instances. For
descriptions of these intrinsics functions, see the Guide to the XUI Toolkit
Intrinsics: C Language Binding.

1.1.1

High-Level Functions
The high-level functions simplify your access to the set of available widgets
and enforce the XUI "look and feel." These functions allow you to
accomplish these goals by presenting you with an argument list representing
the widget attributes that commonly need to be set for such objects as screen
displays, menus, and scroll bars. This set of high-level functions provides
much of the XVI style conforming screen display and user interface tools in
building any application.

Each high-level function begins with the prefix Dwt followed by a name that
aptly describes the widget. For example, the DwtLabel function creates an
instance of a label widget.

1.1.2 Low-Level Functions
Unlike the high-level widget creation functions, the low-level functions
provide you with access to all the widget attributes. Having access to all
widget attributes makes it easier for you to customize widgets. The attributes
of a particular widget include those inherited from superclass widgets and the
widget's own specific attributes.
Like the high-level functions, each low-level function begins with the prefix
Dwt followed by a name that aptly describes the widget. Unlike the highlevel functions, each low-level function name ends with the word Create.
For example, the DwtLabelCreate function creates an instance of a label
widget.
All low-level functions have a common argument list of parent_widget,
name, override_arglist, and override_argcount. For example, the function
definition for DwtLabelCreate is:
Widget DwtLabelCreate (parent_widget, name,

override_arglist, override_argcount)
Widget parent_widget;
char * name ;
ArgList override_arglist;
int override_argcount;

Each low-level function uses a common set of attributes as well as a set of
widget-specific attributes. The widget-specific attributes are described in the
section for that low-level function. The common attributes are described in
Section 1.3.
The declarations and meanings for the low-level function formal parameters
follow:
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies a list of name/value pairs that describes the
attributes of the created widget. This name identifies the
common or widget-specific attribute name associated with the
widget. For example, the x argument is named DwtNx.
The value specifies the value assigned to the previously
named argument. The override arglist can contain any of
the attributes permitted by the Widget's class hierarchy (see
Section 1.2).

1-2 Programming Considerations

By specifying the inherited attributes in the override_ arglist,
you can override the default values inherited from the
superclass widget. By specifying widget-specific attributes in
the override_arglist, you can further customize your widget.
override_argcount
Specifies the number of attributes in the application override
argument list (override _ arglist).

1.1.3

User Interface Language
The User Interface Language (UIL) compiler is a tool in the XUI Toolkit that
helps you create widgets. Using the UIL, you can specify the following:
•

The widgets that comprise your interface

•

The characteristics (attributes) of the widgets you specify

•

The hierarchy of widgets in your application.

For a description of the UIL language and compiler, see the Guide to the XUI
User Inteiface Language Compiler.

1.2 Widget Class Hierarchy
Inherited attributes are determined by the widget's position in the widget
class hierarchy. Within the widget class hierarchy, widgets inherit default
values for attributes from all their superclass widgets. Figure 1-1 shows the
widget class hierarchy.

Programming Considerations 1-3

......

.1.
"tJ
a
co

'TI

$lJ
3
3
5"
co

ii"
e

(I)

....
....
:ea:

()
0

::J

(t)

$lJ

::J

....
(I)

Sir

tn
tn

:I:
CD"
~

m
~

(')

:::T

ZK-0116U-R

Because attributes of several of the top-level widget classes (core, composite,
common) are inherited by the majority of widgets, these attributes are called
common attributes. Common attributes are described in Section 1.3.
Exceptions to the rule that widgets inherit attributes from their superclass
widgets take two fonns: either an inherited attribute is not supported by the
widget, or the inherited attribute has a different default value than the one for
its superclass widget.
As stated in the previous section, you can override the default value of
inherited attributes and use widget-specific attributes to further customize
your widget by specifying them in the override_ arglist.
All widgets belong to classes that are arranged in a hierarchy. Some classes
contain only one widget. For example, the push button class contains only
the push button widget. Other classes contain multiple widgets. The menu
and dialog classes each contain several widgets. Widget attributes reside in
the widget classes.

1.3 Common Attributes
Table 1-1 lists the core widget and common widget attributes that are
inherited by a majority of widgets. Following the table are descriptions of
each attribute. Because the composite class has no user settable attributes,
none are listed here.

Table 1-1: Core Widget and Common Widget Attributes
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Widget-specific
Widget-specific
One pixel
Default foreground color

Attribute Name

Core Attributes

NULL
Default background color

NULL
Default color map
True

Programming Considerations 1-5

Table 1-1:

(continued)

Attribute Name

Data Type

Default

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

DwtNx

Specifies the placement, in pixels, of the left side of
the widget window relative to the inner upper left
comer of the parent window.

DwtNy

Specifies, in pixels, the placement of the top of the
widget window relative to the inner upper left comer
of the parent window.

DwtNwidth

Specifies in pixels the width of the widget window.

DwtNheight

Specifies in pixels the height of the widget window.

DwtNborderWidth Specifies in pixels the border width of the widget

window.
DwtNborder

Specifies the widget window border color.

DwtNborderPixmap Specifies the widget window border pattern and

color.
DwtNbackground

1-6 Programming Considerations

Specifies the color of background objects in the
widget window.

DwtNbackgroundPixmap
Specifies the color and pattern of background objects
in the widget window.
DwtNcolormap

Specifies the color map used for the widget's
window.

DwtNsensitive

Specifies a boolean value that, when True,
indicates the widget reacts to input events. If
False, the widget ignores input events.

DwtNancestorSensitive
Specifies a boolean value that, when True,
indicates that the parent of this widget is sensitive.
If False, the parent of this widget is not sensitive.
You can obtain the value for this attribute by calling
XtGetValues. Your application should not
explicitly set the value of this attribute.
DwtNaccelerators Specifies a translation table that provides an alternate
mode of access to widget functions. Accelerators
allow applications to define keystrokes (in addition to
clicking on a screen object with the mouse) to
activate a function in a widget.
DwtN depth

Specifies the widget window depth. This attribute is
set at widget creation time, and cannot be changed by
the X intrinsics function XtSetValues.

DwtNtranslations Specifies the translation table that contains the
translation manager syntax for associating particular
X events with particular widget events. See the
Guide to Writing Applications Using XUI Toolkit
Widgets for information on translation tables.
DwtNmappedWhenManaged
Specifies a boolean value that, when True, causes
the widget window to be displayed when managed.
If False, the widget window will not be displayed
when managed.
DwtNscreen

Specifies a pointer to the Xlib Screen structure
which contains the information about that screen and
is linked to the Display structure. See the Guide
to the Xlib Library: C Language Binding for
information on the Screen structure.

DwtNdestroyCallback
Specifies the callback function or functions called
when the widget is about to be destroyed. Unlike all
other toolkit callbacks, DwtNdestroyCallback

Programming Considerations 1-7

returns only two valid arguments: widget_id and
tag. The callback_data argument is NULL.
Therefore, applications should avoid setting
DwtNdestroyCallback to call general callback
functions (for example, functions to handle activate,
arm, disarm, and similar actions), because these
functions depend on the callback_data argument.
DwtNforeground

Specifies the color of foreground objects in the
widget window.

DwtNhighlight

Specifies the color used for highlighting.

DwtNhighlightPixmap
Specifies the pattern and color used for highlighting.
DwtNuserData

Specifies any user private data to be associated with
the widget. The XUI Toolkit does not interpret this
data.

Specifies the font of the text used in the widget.

DwtNhelpCallback Specifies the callback function or functions called
when a help request is made.

1.4 Include Files
To make the XUI Toolkit constants and their values available to your
applications, use the include preprocessor statement to include these files:
#include <Xll/Xlib.h>
#include <Xll/DwtWidget.h>
#include <Xll/DwtAppl.h>

1.5 The Callback Facility
The XUI widget and X intrinsics functions make it easier for you to create
and display common application objects such as push buttons. However,
these widget functions cannot determine your user's responses, which would

1-8 Programming Considerations

indicate a change in the widget's state. For example, you might have a file
selection box that contains Ok and Cancel push buttons. When the user
presses either of these push buttons you would want the application to do
something appropriate. This means executing one or more functions that are
private to the application. Thus, there must be some mechanism for the
widget functions to "call back" application private functions, based on some
change in the widget state. This mechanism is referred to as the callback
facility. You can use this callback facility with both the high-level and the
low-level functions.
At creation time (or later using XtSetValues), you specify in your
application the callback function or functions for a widget instance. Each
widget has a (possibly NULL) set of reasons for issuing callbacks, depending
upon how many changes in state it is willing to communicate.
There are a number of constants that represent widget-specific callback
reasons. Each begins with the prefix Dwt followed by some appropriate
name. For example, DwtNacti vateCallback is usually invoked when
the user performs some action such as activating a push button. Examples of
other constants representing widget-specific callback structures are
DwtNselectCallback, DwtNmapCallback,and
DwtNhelpCallback. Most widgets support the common
DwtNhelpCallback attribute.
The basic structure used when specifying callback functions for a callback
reason is a NULL-terminated list of the following entries:
typedef struct {
void
(*proc) ();
Opaque tag;
} DwtCallback, *DwtCallbackPtr;

proc

Specifies a pointer to the callback procedure entry point.

tag

Specifies any application supplied value. This value is
usually used by the application to identify uniquely a
particular widget instance, and to allow one callback function
to service multiple widget instances.
By having more than one entry in a callback list for each
callback reason supported by a widget, the application can
specify more than one function to be called back when the
appropriate widget change in state occurs.

The format for an application's callback function follows:

Programming Considerations 1-9

void CallBackProc (widget id, tag, callback_data)
Widget *widget_id;
Opaque tag;
Dw-tAnyCallbackStruct * callback_data;

Specifies the widget ID associated with the widget
performing the callback.

tag

Identifies the tag provided when the callback was specified.

callback data Specifies a widget-specific data structure.
The format shows the declaration using DwtAnyCallbackStruct.
However, you can also specify callback_data with any of the structures listed
in Table 1-2.

Table 1-2: Callback Structure Names
Structure Name

Widget(s)

DwtAnyCallbackStruct

Main Window, Push
Button, Label, Pull-Down
Menu Entry, Dialog Box,
Attached Dialog Box, Text,
Work-in-Progress Box,
Message Box, Caution Box,
Help, Label Gadget, Push
Button Gadget
Menu (menu work area,
pull-down menu, pop-up
menu, and option menu)
and Menu Bar
Scroll Bar
Toggle Button, Toggle
Button Gadget
Window
Scale
List Box
Radio Box
Selection Box
File Selection Box
Command Window
Compound String Text
Color Mix

DwtMenuCallbackStruct

DwtScrollBarCallbackStruct
DwtTogglebuttonCallbackStruct
DwtWindowCallbackStruct
DwtScaleCallbackStruct
DwtListBoxCallbackStruct
DwtRadioBoxCallbackStruct
DwtSelectionCallbackStruct
DwtFileSelectionCallbackStruct
DwtCommandWindowCallbackStruct
DwtCSTextCallbackStruct
DwtColorMixCallbackStruct

1-10 Programming Considerations

You can declare and pass as many of these structures as needed by the
widget. Each of these structures is discussed with the appropriate functions.
Each data structure has a reason member and an event member. Note that
DwtAnyCallbackStruct only has these two members. The other
structures have additional members to supply you with the appropriate
information. For example, DwtFileSelectionCallbackStruct has
these additional members: value, value_len, dirmask, and dirmask_Ien. The
reason member specifies the reason why this callback function was invoked.
This member allows the application to invoke one callback function for a
variety of reasons. The list of reasons is widget-specific; therefore, these
reasons (along with the other members of the structure) are discussed with
the function in the following chapters.
After you create a widget instance, your application should use
XtAddCallback, XtAddCallbacks, XtRernoveCallback, and
XtRernoveCallbacks to modify a widget callback list. You can use
Xt SetVal ues and XtGetVal ues to set the entire callback list, which

may contain callbacks added by the parent widget.

1.6 Function Format
Each function and its associated formal parameters is shown according to
how it is defined in the XUI Toolkit library. For example, the definition of
the DwtLabel function and its associated formal parameters is:
Widget DwtLabel (parent_widget, name, x, y, label, help_callback)
Widget parent_widget;
char * name;
Position x, y;
DwtCornpString label;
DwtCallbackPtr help_callback;

The function definition gives you the following information:
•

Return type
If the function returns a value, it is indicated in the function definition.
For DwtLabel the return type is a widget ID. If the function does not
return a value, the data type void is indicated.

•

Function name
In this example, the function name is DwtLabel.

•

Number and name of the function's formal parameters
In this example there are six formal parameters: parent_widget, name,
x, y, label, and help_callback.

Programming Considerations 1-11

•

How the function's formal parameters are declared
In this example, parent_widget is of type Widget; name is a pointer
to a character string; x and yare of type Position; label is of type
DwtCompString; and help_callback is a pointer to the structure
DwtCallbackPtr.

In order to eliminate any ambiguity between those arguments that you
pass and those that a function returns to you, the explanations for all
arguments that you pass start with the word "specifies." By contrast,
the explanations for all arguments that are returned to you start with the
word "returns."

1-12 Programming Considerations

PART TWO: WIDGET FUNCTIONS

Window Widget Functions

This chapter discusses the functions you use to create instances of the
following widgets:
•

Application main window

•

Menu bar

•

Window

•

Scroll window

Because you attach a menu bar to a window, it is discussed here rather than
in Chapter 4. This chapter continues with a discussion of two functions: one
to add sub widgets to the application main window, and the other to add a
window region and a vertical or horizontal scroll bar to the scroll window.

2.1

Creating the Application Main Window
The first task of your application is to display a window. A window consists
of a rectangular area with the following:
•

A title bar at the top that identifies the window

•

An optional menu bar directly beneath the title bar that provides access
to the commands of the application

•

A work area in the space remaining that displays the text and graphics
related to the function of the application

The title bar is the horizontal bar that identifies your application and allows
the user to manage the window. The window manager supplies the title bar
for each window of your application and is the program that manages the
positioning and size of windows.
The work area is the portion of the window in which users perform most
application tasks. For example, if a user is working with a text editor, the
work area contains the document being edited. You can create a work area
widget by calling DwtDialogBox. For a discussion of dialog boxes and
their associated functions, see Chapter 5. For more information on the
appearance and operation of standard XUI windows, see the XU! Style Guide.

To create an instance of the main window widget, use DwtMainWindowor
DwtMainWindowCreate. When calling DwtMainWindow, you set the
main window widget attributes presented in the formal parameter list. For
DwtMainWindowCreate, however, you specify a list of attribute
name/value pairs that represent all the possible attributes of the main window
widget. After you create an instance of this widget, you can manipulate it
using the appropriate X intrinsics functions. A description of each follows:
Widget DwtMainWindow (parent_widget, name, x, y, width, height)
Widget parent_widget;
char * name ;
Position x, y;
Dimension width, height;
parent_widget Specifies the parent widget ID. For some applications, the
parent widget ID for the main window widget is the ID
returned by XtInitialize. However, the main window
widget is not restricted to this type of parent.
name

Specifies the name of the. created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

width

Specifies in pixels the width of the widget window. This
argument sets the DwtNwidth core widget attribute.

height

Specifies in pixels the height of the widget window. This
argument sets the DwtNheight core widget attribute.

Widget DwtMainWindowCreate (parent_widget, name,
override_argUst, override_argcount)
Widget parent_widget;
char * name ;
ArgList override_argUst;
int override_argcount ;
parent_widget Specifies the parent widget ID. For some applications, the
parent widget ID for the main window widget is the ID
returned by XtInitialize. However, the main window
widget is not restricted to this type of parent.

2-2 Window Widget Functions

name

Specifies the name of the created widget.

2.1.1

•

Callback information

•

Geometry management

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRFocus

The main window widget has received the
input focus.

DwtCRHelpRequested

The user selected help.

2.1.2

Geometry Management
The main window widget tiles the insides of its window with up to five
children as follows:

Window Widget Functions 2-3

•

The child widget designated as the menu bar widget is placed at the top
and extends all the way across the main window. The height of the
menu bar widget is set to whatever the menu requests.

•

The child widget designated as the command widget is placed at the
bottom and extends all the way across the main window. The height of
the command widget is not altered.

•

The child widget designated as the horizontal scroll bar widget is placed
just above the command widget (if there is no command widget, it is
placed at the bottom of the main window). The width of the horizontal
scroll bar is the width of the main window minus the width of the
vertical scroll bar. The height of the horizontal scroll bar is not altered.

•

The child widget designated as the vertical scroll bar widget is placed
on the right edge below the menu bar. The height is the distance
between the bottom of the menu bar and the top of the horizontal scroll
bar. The width of the vertical scroll bar is not altered.

•

The child widget designated as the work area widget fills the area under
the menu bar, to the left of the vertical scroll bar, and above the
horizontal scroll bar. Both the width and height are altered.

There are three ways to designate that a child fill one of the previously
described roles. The first is to call the DwtMainSetAreas function (see
Section 2.5), which allows you to pass the ID of the child you want to
associate with a particular role. The second is to call the X intrinsics
function XtSetValues and set the area attributes with the appropriate
widget IDs. The third method is to let the main window widget determine
which child fulfills which role by using the following algorithm since only
currently managed children are eligible to be designated for a role:
•

A child of menu widget class (or subclass) is assumed to be the menu
bar widget.

•

A child of command widget class (or subclass) is assumed to be the
command widget.

•

A child of scroll widget class (or subclass) is either the horizontal or
vertical scroll bar widget, which is determined by looking at the
DwtNorientation attribute of the child.

•

A child of any other class is assumed to be the work area.

For many applications, however, calling DwtMainSetAreas or
XtSetValues is redundant, since a single main window widget may have
a number of menu bars as children. Thus, by managing and unmanaging the
menu bar children appropriately, the application can switch between menu
bars without using DwtMainSetAreas or XtSetVal ues.

2-4 Window Widget Functions

You can specify the size of the main window widget in two ways:
•

Specify a nonzero width and height at widget creation time.
In this case, the main window widget does not change its size on a
geometry request by one of its children.

•

Specify zero for both width and height at widget creation time.
In this case, the main window widget uses the width and height of the
widget designated as the work area widget in determining its width and
height. The main window widget does not alter the width and height of
the work area widget and places the remaining widgets based on the
work area's size. The work area widget can later request a size change,
and the main window widget will honor the request and reconfigure its
size.

As a geometry manager, the main window widget allows the following
requests to be completed:
•

Changing the height of the menu bar, command window, and horizontal
scroll bar widgets.

•

Changing the width of the vertical scroll bar widget.

•

Changing the width and height of the work area widget, if the main
window widget was created with width and height of zero.

When resized, the main window widget reformats itself as described
previously.

2.1.3

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the main window widget is:
•
•

core
composite

•
•

common
main window

Based on this class hierarchy, the main window widget inherits attributes
from the core, composite, and common widgets. Note that you cannot set the
attributes for the composite widget; therefore, they are not shown.
Table 2-1 lists the attributes inherited by the main window widget. For
descriptions of the core and common attributes, see Chapter 1.

Window Widget Functions 2-5

Table 2-1: Attributes Inherited by the Main Window Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Determined by the geometry
manager
Determined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Core Attributes

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

2-6 Window Widget Functions

Pixel
NOT SUPPORTED
NOT SUPPORTED
Opaque *
unsigned char
NOT SUPPORTED
DwtCallbackptr

Default foreground color

NULL
DwtDirectionRightDown
NULL

2.1.4

Widget-Specific Attributes
Table 2-2 lists the widget-specific attributes for the main window widget.
Descriptions of these attributes follow the table.

Table 2-2: Widget-Specific Attributes for the Main Window
Widget
Attribute Name

Data Type

Default

DwtNcommandWindow
DwtNworkWindow
DwtNmenuBar
DwtNhorizontalScrollBar
DwtNverticalScrollBar
DwtNacceptFocus
DwtNfocusCallback

Widget
Widget
Widget
Widget
Widget
Boolean
DwtCallbackptr

NULL
NULL
NULL
NULL
NULL
False

NULL

DwtNcommandWindowSpecifies the widget ID for the command window to
be associated with the main window widget. You
can set this ID only after creating an instance of the
main window widget.
DwtNworkWindow

Specifies the widget ID for the work window to be
associated with the main window widget. You can
set this ID only after creating an instance of the main
window widget.

DwtNmenuBar

Specifies the widget ID for the menu bar to be
associated with the main window widget. You can
set this ID only after creating an instance of the main
window widget.

DwtNhorizontalScrollBar
Specifies the scroll bar widget ID for the horizontal
scroll bar in the main window widget. You can set
this ID only after creating an instance of the main
window widget.
DwtNverticalScrollBar
Specifies the scroll bar widget ID for the vertical
scroll bar in the main window widget. You can set
this ID only after creating an instance of the main
window widget.

Window Widget Functions 2-7

DwtNacceptFocus Specifies a boolean value that, when False,
indicates that the main window widget does not
accept the input focus. When the main window
widget is asked to accept the input focus, it attempts
to give the input focus first to DwtNworkWindow
and then to DwtNcommandWindow. If neither
accepts the input focus and DwtNacceptFocus is
True, the main window widget accepts the input
focus.
DwtNfocusCallbackSpecifies the callback function or functions called
when the main window has accepted the input focus.
For this callback, the reason is DwtCRFocus.

2.2 Creating the Menu Bar
The menu bar, a horizontal bar that contains lists of application commands
called menus, is located immediately below the title bar and extends the full
width of the window. If the space required for the menu names exceeds the
window width, the menu bar will wrap to as many lines as necessary.
Because menus are the principal form of command interaction for XUI
applications, most applications that accept user input require a menu bar. For
more detailed information about menus, see Chapter 4.
To create an instance of the menu bar widget, use DwtMenuBar or
DwtMenuBarCreate. When calling DwtMenuBar, you set the menu bar
widget attributes presented in the formal parameter list. For
DwtMenuBarCreate, you specify a list of attribute name/value pairs that
represent all the possible menu bar widget attributes. After you create an
instance of this widget, you can manipulate it using the appropriate X
intrinsics functions. A description of each follows:
Widget DwtMenuBar (parent_widget, name, entry_callback,
help_callback)
Widget parent_widget;
char * name ;
DwtCallbackPtr entry_callback;
DwtCallbackPtr help_callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

2-8 Window Widget Functions

DwtNentryCallback attribute associated with
DwtMenuCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtMenuBarCreate (parent_widget, name,
override_ arglist, override_argcount)
Widget parent_widget;
char * name;
ArgLi st override_arglist ;
in t override_ argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtMenuBar and DwtMenuBarCreate functions create an instance
of the menu bar widget and return its associated widget ID.
A menu bar widget is a composite widget that contains pull-down menu
entry subwidgets. The subwidgets handle most of the I/O activity that
display information and query the user for input. The menu bar widget
provides no input semantics over and above those provided by its
sub widgets.
If the menu bar does not have enough room to fit all its subwidgets on a
single line, the menu bar attempts to wrap the remaining entries onto
additional lines (if allowed by the geometry manager of the parent widget).

The menu bar widget works with these widget classes: pull-down menu
entries, labels, and separators.
If DwtNentryCallback is not NULL when it is activated, all subwidgets
call back to this callback. Otherwise, the individual subwidgets handle the
activation callbacks.

The geometry management and resizing for the menu bar widget are identical
to that described for the menu widget. For a discussion of geometry
management and resizing, see Chapter 4. The following sections discuss
these aspects of the menu bar widget:
•

Callback information

•

Widget class hierarchy and inherited attributes

Window Widget Functions 2-9

2.2.1

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
Widget s_widget;
char *s_tag;
char *s_callbackstruct;
DwtMenuCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActi vate

The user selected a menu entry.

DwtCRMap

The menu window is about to be mapped.

DwtCRUnmap

The menu window was just unmapped.

DwtCRHelpRequested

The user selected help.

The event member is a pointer to the Xlib structure XEvent, which
describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding. The s_widget member is set to the ID of the activating
subwidget. The s_tag member is set to the tag supplied by the application
programmer when the subwidget callback function was specified. The
s_callbackstruct member is set to the subwidget's callback structure.

2.2.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the menu bar widget is:
•
•

core
composite

•

common

•
•

menu
menu bar

Based on this class hierarchy, the menu bar widget inherits attributes from
the core, composite, common, and menu widgets. Note that you cannot set
the attributes for the composite widget; therefore, they are not shown.

2-10 Window Widget Functions

Note also that the menu bar widget does not support any widget-specific
attributes.
Table 2-3 lists the attributes inherited by the menu bar widget. For
descriptions of the core and common attributes, see Chapter 1. For
descriptions of the menu attributes, see Chapter 4.

Table 2-3: Attributes Inherited by the Menu Bar Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight

Dimension
Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Detennined by the geometry
manager
Detennined by the geometry
manager
16 pixels
Number of lines needed to display
all entries
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
Note that setting the sensitivity of
the menu bar causes all widgets
contained in that menu bar to be
set to the same sensitivity as the
menu bar.
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel

Default foreground color
Default foreground color

Core Attributes

Common Attributes
DwtNforeground
DwtNhighlight

Window Widget Functions 2-11

Table 2-3:

(continued)

Attribute Name

Data Type

Default

DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr

NULL
NULL
DwtDirectionRightDown
Used only by gadget children
NULL

DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char
unsigned char

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

Widget Class

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

Widget
DwtCallbackptr
Widget
Boolean
Boolean

One pixel
Zero pixels
Three pixels
DwtOrientationVertical
True
Zero pixels
True
DwtAlignmentBeginning
DwtMenuPackingTight(fur
all menu types except for radio
boxes)
DwtMenuPackingColumn(fur
radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)
NULL
Radio boxes, however, default to
the togglebuttonwidgetc1ass.
Zero
NULL
NULL
True
True

Menu Attributes

2-12 Window Widget Functions

2.3 Creating a Window Widget
Since some XUI Toolkit applications may require a more direct interface for
creating window widgets, the window widget simplifies programming by
allowing you to create an application display directly in the main window
widget work area. To create an instance of the window widget, use
DwtWindowor DwtWindowCreate. When calling DwtWindow, you
set the window widget attributes presented in the formal parameter list. For
DwtWindowCreate, you specify a list of attribute name/value pairs that
represent all the possible window widget attributes. After you create an
instance of this widget, you can manipulate it using the appropriate X
intrinsics functions. A description of each follows:
Widget DwtWindow (parent_widget, name, x, y, width,
height, callback)
Widget parent_widget;
char * name;
Position x, y;
Dimension width, height;
DwtCallbackPtr callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the top of the widget
window relative to the inner upper left comer of the parent
window. This argument sets the DwtNy core widget
attribute.

width

Specifies in pixels the width of the widget window. This
argument sets the DwtNwidth core widget attribute.

height

Specifies in pixels the height of the widget window. This
argument sets the DwtNheight core widget attribute.

callback

Specifies the callback function or functions called when an
Expose event occurs. This argument sets the
DwtNexposeCallback attribute associated with
DwtWindowCreate.

Window Widget Functions 2-13

Widget DwtWindowCreate (parent_widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char * name;
ArgList override_arglist;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

2.3.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XExposeEvent *event;
Window w;
DwtWindowCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRExpose

The window widget had an Expose event.

The event member is a pointer to the Xlib structure XExposeEvent. This
structure is associated with exposure event processing, and, specifically, with
Expose events. For information on exposure event processing, see the
Guide to the Xlib Library: C Language Binding.

2-14 Window Widget Functions

The members of the XExposeEvent structure associated with Expose
events are window, x, y, width, height, and count. The window member is
set to the window ID of the exposed (damaged) window. The x and y
members are set to the coordinates relative to the drawable's origin and
indicate the upper-left corner of the rectangle. The width and height
members are set to the size (extent) of the rectangle. The count member is
set to the number of Expose events that are to follow. If count is set to
zero (0), no more Expose events follow for this window. However, if
count is set to nonzero, at least count Expose events and possibly more
follow for this window. Simple applications that do not want to optimize
redisplay by distinguishing between subareas of its windows can just ignore
all Expose events with nonzero counts and perform full redisplays on
events with zero counts.
The w member is set to the X window ID where the Expose event
occurred.

2.3.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the window widget is:
•
•

core
composite

•
•

common
window

Based on this class hierarchy, the window widget inherits attributes from the
core, composite, and common widgets. Note that you cannot set the
attributes for the composite widget; therefore, they are not shown.
Table 2-4 lists the attributes inherited by the main window widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 2-4: Attributes Inherited by the Window Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth

Dimension
Dimension
Dimension

Determined by the geometry
manager
Determined by the geometry
manager
Widget-specific
Widget-specific
One pixel

Core Attributes

Window Widget Functions 2-15

Table 2-4:

(continued)

Attribute Name

Data Type

Default

DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Default foreground color
NULL
Default background color
NULL
Default color map
True
Setting the sensitivity of the
window causes all widgets
contained in that window to be
set to the same sensitivity as the
window.
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
NOT SUPPORTED

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown

2.3.3 Widget-Specific Attributes
Table 2-5 lists the widget-specific attribute for the window widget. The
description of this attribute follows the table.

2-16 Window Widget Functions

Table 2-5: Widget-Specific Attributes for the Window Widget
Attribute Name

Data Type

Default

DwtNexposeCallback

DwtCallbackptr

NULL

DwtNexposeCallback
Specifies the callback function or functions called
when the window had an Expose event. For this
callback, the reason is DwtCRExpose.

2.4 Creating a Scroll Window Widget
Since some XUI Toolkit applications may require a more direct interface for
creating scroll bar widgets, the scroll window widget simplifies programming
by allowing you to create an application with scroll bars directly in the main
window widget work area.
To create an instance of the scroll window widget, use
DwtScrollWindowor DwtScrollWindowCreate. When calling
DwtScrollWindow, you set the scroll window widget attributes presented
in the formal parameter list. For DwtScrollWindowCreate, you
specify a list of attribute name/value pairs that represent all the possible
scroll window widget attributes. After you create an instance of this widget,
you can manipulate it using the appropriate X intrinsics functions. A
description of each follows:
Widget DwtScrollWindow (parent_widget, name, x, y,
width, height)
Widget parent_widget;
char * name ;
Position x, y;
Dimension width, height;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the top of the widget
window relative to the inner upper left comer of the parent
window. This argument sets the DwtNy core widget
attribute.
Window Widget Functions 2-17

width

Specifies in pixels the width of the widget window. This
argument sets the DwtNwidth core widget attribute.

height

Specifies in pixels the height of the widget window. This
argument sets the DwtNheight core widget attribute.

Widget DwtScrollWindowCreate (parent_widget, name,
override_arglist ,
override_argcount )
Widget parent_widget;
char *name;
ArgLi st override_arglist ;
int override_argcount;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtScrollWindowand DwtScrollWindowCreate functions
create an instance of a scroll window widget and return its associated widget
ID. This widget provides a more direct XUI interface for applications with
scroll bars. The DwtScrollWindowand DwtScrollWindowCreate
functions create a composite widget that can contain vertical and horizontal
scroll bar widgets and any widget as the window region. Scroll bar
positioning and scroll bar slider sizes are automatically maintained. The
scroll window widget simplifies programming by allowing you to create an
application with scroll bars directly in the scroll window widget work area.
The following sections discuss these aspects of the scroll window widget:

2.4.1

•

Geometry management and resizing

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Geometry Management and Resizing
The scroll window widget does not do any sizing or positioning of the
widget that is the work region of the scroll window widget. However, the
scroll window widget does position and size the scroll bars.
The scroll window widget automatically resizes the scroll bars, but not the
widget that is the work region.

2-18 Window Widget Functions

2.4.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the scroll window widget is:
•
•

core
composite

•
•

common
scroll window

Based on this class hierarchy, the scroll window widget inherits attributes
from the core, composite, and common widgets. Note that you cannot set the
attributes for the composite widget; therefore, they are not shown.
Table 2-6 lists the attributes inherited by the scroll window widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 2-6: Attributes Inherited by the Scroll Window Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Widget-specific
Widget-specific
One pixel
Default foreground color

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged

XtTranslations
int
XtTranslations
Boolean

Core Attributes

NULL
Default background color

NULL
Default color map
True
Setting the sensitivity of the scroll
window causes all widgets
contained in that window to be
set to the same sensitivity as the
scroll window.
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True

Window Widget Functions 2-19

Table 2-6:

(continued)

Attribute Name

Data Type

Default

DwtNscreen
DwtNdestroyCallback

Screen *
DwtCallbackptr

The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
NOT SUPPORTED

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

2.4.3 Widget-Specific Attributes
Table 2-7 lists the widget-specific attributes for the scroll window widget.
Descriptions of these attributes follow the table.

Table 2-7: Widget-Specific Attributes for the Scroll Window
Widget
Attribute Name

Data Type

Default

DwtNhorizontalScrollBar
DwtNverticalScrollBar
DwtNworkWindow
DwtNshownValueAutomaticHoriz
DwtNshownValueAutomaticVert

Widget
Widget
Widget
Boolean
Boolean

NULL
NULL
NULL
True
True

DwtNhorizontalScrollBar
Specifies the scroll bar widget ID for the horizontal
scroll bar to be associated with the scroll window
widget. You can set this ID only after creating an
instance of the main window widget.
DwtNverticalScrollBar
Specifies the scroll bar widget ID for the vertical
scroll bar to be associated with the scroll window
widget. You can set this ID only after creating an

2-20 Window Widget Functions

instance of the main window widget.
DwtNworkWindow

Specifies the widget ID for the work window to be
associated with the scroll window widget. You can
set this ID only after creating an instance of the main
window widget.

DwtNshownValueAutomaticHoriz
Specifies a boolean value that, when True,
indicates that DwtScrollWindowautomatically
sets the value for the DwtNshown attribute for the
specified horizontal scroll bar widget.
DwtNshownValueAutomaticVert
Specifies a boolean value that, when True,
indicates that DwtScrollWindowautomatically
sets the value for the DwtNshown attribute for the
specified vertical scroll bar widget.

2.5 Adding Subwidgets to the Main Window
There are at least two ways to add sub widgets to the main window. The first
is to create an instance of the main window widget by calling
DwtMainWindow or DwtMainWindowCreate and then to use
X t Set Va 1 u e s to specify the subwidget ID of the specified subwidgets
(menu bar, work area, command area, and scroll bars). The second is to
create an instance of the main window widget and then call the
DwtMainSetAreas function.
void DwtMainSetAreas (widget, menu_bar, work_window,
command_window, horizontal_scroll_bar,
vertical_scroll_bar)
Widget widget;
Widget menu_bar;
Widget work_window, command_window;
Widget horizontal_scroll_bar, vertical_scroll_bar;

widget

Specifies the main window widget ID.

menu bar

Specifies the widget ID for the menu bar to be associated
with the main window widget. You can set this ID only after
creating an instance of the main window widget. The
attribute name associated with this argument is
DwtNmenuBar.

Window Widget Functions 2-21

work window Specifies the widget ID for the work window to be associated
with the main window widget. You can set this ID only after
creating an instance of the main window widget. The
attribute name associated with this argument is
DwtNworkWindow.

command window
-

Specifies the widget ID for the command window to be
associated with the main window widget. You can set this
ID only after creating an instance of the main window
widget. The attribute name associated with this argument is
DwtNcommandWindow.

horizontal scroll bar
-

Specifies the scroll bar widget ID for the horizontal scroll bar
to be associated with the main window widget. You can set
this ID only after creating an instance of the main window
widget. The attribute name associated with this argument is
DwtNhorizontalScrollBar.

vertical scroll bar
-

- Specifies the scroll bar widget ID for the vertical scroll bar to
be associated with the main window widget. You can set
this ID only after creating an instance of the main window
widget. The attribute name associated with this argument is
DwtNverticalScrollBar.

The DwtMainSetAreas function sets up or adds the menu bar, work
window, command window, and scroll bar widgets to the application's main
window widget. You must set these areas up before the main window widget
is realized, that is, before calling the X intrinsics function
XtRealizeWidget.
Each area is optional; therefore, you can pass NULL to one or more of these
arguments. The title bar is provided by the window manager.

2.6 Adding a Window Region and Scroll Bar
To add a window region and the scroll bar to the scroll bar widget window,
use DwtScrollWindowSetAreas:
void DwtScrollWindowSetAreas (widget, horizontal scroll bar,

vertical_scroll_bar, - work=region)
Widget
Widget
Widget
Widget

widget;
horizontal_scroll_bar;
vertical scroll bar;
work_region;-

2-22 Window Widget Functions

widget

Specifies the scroll window widget ID.

horizontal scroll bar
Specifies the scroll bar widget ID for the horizontal scroll bar
to be associated with the scroll window widget. You can set
or specify this ID only after creating an instance of the main
window widget. The attribute name associated with this
argument is DwtNhorizontalScrollBar.
vertical scroll bar
- Specifies the scroll bar widget ID for the vertical scroll bar to
be associated with the scroll window widget. You can set or
specify this ID only after creating an instance of the main
window widget. The attribute name associated with this
argument is DwtNverticalScrollBar.
work_region

Specifies the widget ID for the window to be associated with
the scroll window work area. You can set or specify this ID
only after you create an instance of the main window widget.

The DwtScrollWindowSetAreas function adds or changes a window
work region and a horizontal or vertical scroll bar widget to the scroll
window widget for the application. You must call this function before the
scroll window widget is realized, that is, before calling the X intrinsics
function XtRealizeWidget. Each widget is optional and may be passed
as NULL.

Window Widget Functions 2-23

Subarea Widget Functions

Your application's work area can be divided into subareas. Subareas can
contain application-related work; they can also contain controls, which are
screen objects that allow the user to provide input to the application. The
XUI Toolkit provides functions that allow you to create instances of subarea
widgets. This chapter discusses the functions you can use to:

3.1

•

Create a scroll bar widget

•

Obtain and set the scroll bar slider position

•

Create a label widget

•

Create a toggle button widget

•

Obtain and set toggle button widget state

•

Create a radio box widget

•

Create a push button widget

•

Create a scale widget

•

Obtain and set the scale slider position

Creating the Scroll Bar
The scroll bar allows the user to view information or a file that is too
extensive to be displayed all at one time in a work area or another subarea.
A scroll bar consists of two stepping arrows at either end of an elongated
rectangle called the scroll region. A smaller rectangle called a slider resides
in the scroll region. The stepping arrows and the slider allow the user to
move the work area over the underlying file. The scroll region represents the
underlying file. The position of the slider in the scroll region is relative to
the work area's position in the underlying file.
Work areas or other subareas may have a vertical or horizontal scroll bar, or
both. Horizontal scroll bars are on the bottom edge of the work area or
subarea they control, and vertical scroll bars are on the right edge. For
information on operating scroll bars, see the XUI Style Guide. To create an
instance of the scroll bar widget, use DwtScrollBar or
DwtScrollBarCreate. When calling DwtScrollBar, you set the
scroll bar widget attributes presented in the formal parameter list. For
DwtScrollBarCreate, however, you specify a list of attribute

name/value pairs that represent all the possible scroll bar widget attributes.
Mter you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions. A description of each follows:
Widget DwtScrollBar (parent_widget, name, x, y,

width, height, inc, page_inc,
shown, value, min_value, max_value,
orientation, callback, help_callback,
unit inc callback, unit dec callback,
page_inc_callback, page_dec_callback,
to top callback, to bottom callback)
drag_callback)
Widget parent_widget;
char * name;
Position x, y;
Dimension width, height;
int inc, page inc;
int shown; int value;
int min_value, max value;
int orientation;
DwtCallbackPtr callback, help callback;
DwtCallbackptr unit inc callback, unit dec callback;
DwtCallbackPtr page_inc_callback, page_iec_callback;
DwtCallbackPtr to_top_callback, to_bottom_callback;
DwtCallbackPtr drag_callback;
parent_widget Specifies the parent widget ID.
Specifies the name of the created widget.
name
x

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

width

Specifies the width of the widget window. This argument
sets the DwtNwidth core widget attribute.

height

Specifies the height of the widget window. This argument
sets the DwtNheight core widget attribute.

inc

Specifies the amount of button increment and decrement. If
this argument is nonzero, the scroll bar widget automatically

3-2 Subarea Widget Functions

adjusts the slider when an increment or decrement action
occurs. This argument sets the DwtNinc attribute
associated with DwtScrollBarCreate.
Specifies the amount of page increment and decrement. If
this argument is nonzero, the scroll bar widget automatically
adjusts the slider when an increment or decrement action
occurs. This argument sets the DwtNpageInc attribute
associated with DwtScrollBarCreate.
shown

Specifies the size of the slider as a value between zero and
the absolute value of DwtNmaxVal ue minus
DwtNminValue. The size of the slider varies, depending
on how much of the slider scroll area it represents. This
argument sets the DwtN shown attribute associated with
DwtScrollBarCreate.

value

Specifies the scroll bar's top thumb position between
DwtNminVal ue and DwtNmaxVal ue. This sets the
DwtNval ue attribute associated with
DwtScrollBarCreate.

min value

Specifies the scroll bar's minimum value. This argument sets
the DwtNminValue attribute associated with
DwtScrollBarCreate.

max value

Specifies the scroll bar's maximum value. This argument
sets the DwtNrnaxVal ue attribute associated with
DwtScrollBarCreate.

orientation

Specifies whether the scroll bar is displayed vertically or
horizontally. You can pass
DwtOrientationHorizontalm
DwtOrientationVertical. This argument sets the
DwtNorientation attribute associated with
DwtScrollBarCreate.

callback

Specifies the callback function or functions called back when
the value of the scroll bar changes. This argument sets the
DwtNvalueChangedCallback attribute associated with
DwtScrollBarCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.

Subarea Widget Functions 3-3

unit inc callback
Specifies the callback function or functions called when the
user selected the down or right unit scroll function. For this
callback, the reason is DwtCRUni tInc. This argument
sets the DwtNuni tIncCallback attribute associated
with DwtScrollBarCreate.
unit dec callback
Specifies the callback function or functions called when the
user selected the above or left unit scroll function. For this
callback, the reason is DwtCRUni tDec. This argument
sets the DwtNuni tDecCallback attribute associated
with DwtScrollBarCreate.
page_inc_callback
Specifies the callback function or functions called when the
user selected the below or right page scroll function. For this
callback, the reason is DwtCRPageInc. This argument
sets the DwtNpageIncCallback attribute associated
with DwtScrollBarCreate.
page_dec_callback
Specifies the callback function or functions called when the
user selected the above or left page scroll function. For this
callback, the reason is DwtCRPageDec. This argument
sets the DwtNpageDecCallback attribute associated
with DwtScrollBarCreate.
to_top_callback Specifies the callback function or functions called when the
user selected the current line to top scroll function. For this
callback, the reason is DwtCRToTop. The scroll bar does
not automatically change the scroll bar's DwtNvalue for
this callback. This argument sets the
DwtNtoTopCallback attribute associated with
DwtScrollBarCreate.
to- bottom- callback
Specifies the callback function or functions called when the
user selected the current line to bottom scroll function. For
this callback, the reason is DwtCRToBottom. The scroll
bar does not automatically change the scroll bar's
DwtNval ue for this callback. This argument sets the
DwtNtoBottomCallback attribute associated with
DwtScrollBarCreate.
drag_callback Specifies the callback function or functions called when the
user is dragging the scroll bar slider. For this callback, the
reason is DwtCRDrag. This argument sets the
DwtNdragCallback attribute associated with
DwtScrollBarCreate.
3-4 Subarea Widget Functions

Widget DwtScrollBarCreate (parent_widget, name,
override_argUst, override_argcount)
Widget parent_widget;
char * name ;
ArgList override_argUst;
int override_ argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_argUstSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _ argUst).

The DwtScrollBar and DwtScrollBarCreate functions create an
instance of a scroll bar widget and return its associated widget ID. The scroll
bar widget is a screen object that the application or user uses to scroll
through display data too large for the screen. This widget consists of two
stepping arrows at either end of an elongated rectangle called the scroll
region. The scroll region is overlaid with a slider bar (thumb) that is
adjusted in size and position (thumb shown) as scrolling occurs using the
function attributes. The stepping arrows and the exposed scroll areas behind
the slider are the scroll activator objects providing the user interface syntax
, 'feel."
Note that the DwtNtoTopCallback and DwtNtoBottomCallback
callbacks do not automatically set the thumb as the other callbacks do.
The following sections discuss these aspects of the scroll bar widget:

3.1.1

•
•

Callback information
Geometry management and resizing

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
int value;
int pixel;
DwtScrollBarCallbackStruct;

Subarea Widget Functions 3-5

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRVal ueChanged

The user changed the value of the scroll bar
slider.

DwtCRUnitInc

The user selected the down or right unit
scroll function.

DwtCRUni tDec

The user selected the up or left unit scroll
function.

DwtCRPageDec

The user selected the above or left page
scroll function.

DwtCRPageInc

The user selected the below or right page
scroll function.

DwtCRToTop

The user selected the current line to top
scroll function.

DwtCRToBottom

The user selected the current line to bottom
scroll function.

DwtCRDrag

The user is dragging the scroll bar slider.

DwtCRHelpRequested

The user selected help.

The event member is a pointer to the Xlib structure XEvent, which
describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding. The value member is set to the slider's current value and
maps to the DwtNvalue attribute. The pixel member is set to the pixel
value from the top right of the scroll bar where the event occurred. This
pixel value is used for the DwtNtoTopCallback and
DwtNtoBottomCallback attributes.

3.1.2

Geometry Management and Resizing
The scroll bar widget does not support children.
If the default core widget attributes DwtNwidth or DwtNheight (0) are
used, the scroll bar is set to the DwtNheight of the parent window
(vertical) or to the DwtNwidth of the parent window (horizontal). If the

3-6 Subarea Widget Functions

default core widget attributes DwtNx or DwtNy (0) are used, the scroll bar
is set to the right of the parent window (vertical) or to the bottom of the
parent window (horizontal). This is also true if you specify DwtNwidth,
DwtNheight, DwtNx, or DwtNy in the call to XtSetValues.

3.1.3

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the scroll bar widget is:
•
•

core
composite

•

common

•
scroll
Based on this class hierarchy, the scroll bar widget inherits attributes from
the core, composite, and common widgets. Note that you cannot set the
attributes for the composite widget; therefore, they are not shown.
Table 3-1 lists the attributes inherited by the scroll bar widget. For
descriptions of the core and common attributes, see Chapter 1.
Table 3-1: Attributes Inherited by the Scroll Bar Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
For vertical scroll bars, 17 pixels.
For horizontal scroll bars, the
width of the parent minus 17
pixels.
For horizontal scroll bars, 17
pixels.
For vertical scroll bars, the height
of the parent minus 17 pixels.
One pixel
Default foreground color

Core Attributes

NULL
Default background color

NULL
Default color map
True

Subarea Widget Functions 3-7

Table 3-1:

(continued)

Attribute Name

Data Type

Default

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

3.1.4

Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
NULL

Widget-Specific Attributes
Table 3-2 lists the widget-specific attributes for the scroll bar widget.
Descriptions of these attributes follow the table.

Table 3-2: Widget-Specific Attributes for the Scroll Bar Widget
Attribute Name

Data Type

Default

DwtNvalue
DwtNminValue
DwtNmaxValue
DwtNorientation
DwtNtranslationsl
DwtNtranslations2
DwtNshown
DwtNinc
DwtNpagelnc
DwtNvalueChangedCallback

int
int
int
unsigned char
XtTranslations
XtTranslations
int
int
int
DwtCallbackPtr

Zero
Zero
100
DwtOrientationVertical
NULL
NULL
10 units
10 units
10 units
NULL

3-8 Subarea Widget Functions

Table 3-2:

(continued)

Attribute Name

Data Type

Default

DwtNunitIncCallback
DwtNunitDecCallback
DwtNpageIncCallback
DwtNpageDecCallback
DwtNtoTopCallback
DwtNtoBottomCallback
DwtNdragCallback
DwtNshowArrows

DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
Boolean

NULL
NULL
NULL
NULL
NULL
NULL
NULL
True

DwtNval ue

Specifies the scroll bar's top thumb position between
DwtNminValue and DwtNmaxValue. This
attribute also appears as a member in
DwtScrollBarCallbackStruct.

DwtNminVal ue

Specifies the scroll bar's minimum value.

DwtNmaxVal ue

Specifies the scroll bar's maximum value.

DwtNorientation Specifies whether the scroll bar is displayed
vertically or horizontally. You can pass
DwtOrientationHorizontalor
DwtOrientationVertical.
DwtNtranslationslSpecifies the translation table for events after being
parsed by the X intrinsics function
XtParseTranslationTable for the decrement
button.
DwtNtranslations2Specifies the translation table for events after being
parsed by the X intrinsics function
XtParseTranslationTable for the increment
button.
DwtNshown

Specifies the size of the slider as a value between
zero and the absolute value of DwtNmaxVal ue
minus DwtNminValue. The size of the slider
varies, depending on how much of the slider scroll
area it represents.

DwtNinc

Specifies the amount of button increment and
decrement. If this argument is nonzero, the scroll bar
widget automatically adjusts the slider when an
increment or decrement action occurs.

Subarea Widget Functions 3-9

DwtNpageInc

Specifies the amount of page increment and
decrement. If this argument is nonzero, the scroll bar
widget automatically adjusts the slider when an
increment or decrement action occurs.

DwtNvalueChangedCallback
Specifies the callback function or functions called
when the value of the scroll bar slider was changed.
For this callback, the reason is
DwtCRVal ueChanged.
DwtNunitIncCallback
Specifies the callback function or functions called
when the user selected the down or right unit scroll
function. For this callback, the reason is
DwtCRUni t Inc.
DwtNunitDecCallback
Specifies the callback function or functions called
when the user selected the above or left unit scroll
function. For this callback, the reason is
DwtCRUni tDec.
DwtNpageIncCallback
Specifies the callback function or functions called
when the user selected the below or right page scroll
function. For this callback, the reason is
DwtCRP ageInc.
DwtNpageDecCallback
Specifies the callback function or functions called
when the user selected the above or left page scroll
function. For this callback, the reason is
DwtCRPageDec.
DwtNtoTopCallbackSpecifies the callback function or functions called
when the user selected the current line to top scroll
function. For this callback, the reason is
DwtCRToTop. The scroll bar does not
automatically change the scroll bar's DwtNval ue
for this callback.
DwtNtoBottomCallback
Specifies the callback function or functions called
when the user selected the current line to bottom
scroll function. For this callback, the reason is
DwtCRToBottom. The scroll bar does not
automatically change the scroll bar's DwtNval ue
for this callback.

3-10 Subarea Widget Functions

DwtNdragCallback Specifies the callback function or functions called

when the user is dragging the scroll bar slider. For
this callback, the reason is DwtCRDrag. The scroll
bar does not automatically change the scroll bar's
DwtNvalue for this callback.
DwtNshowArrows

Specifies a boolean value that, when True,
indicates there are arrows. If False, there are no
arrows.

3.2 Obtaining and Setting the Scroll Bar Slider
Size/Position
The ratio of the slider size to the scroll region size corresponds to the
relationship between the portion of the file appearing in the window and the
size of the file. For example, if 10 percent of a text file actually appears in
the window, the slider takes up 10 percent of the scroll region. This provides
your user with a visual cue to the size of the underlying file. Your
application must maintain the ratio by keeping track of the file size and the
window size. For more information on the slider size, see the XU] Style
Guide.
The XUI Toolkit provides you with functions to obtain and set the slider size
and position. To obtain the slider's currently displayed size/position values,
use DwtScrollBarGetSlider. To change the current slider
size/position value, use DwtScrollBarSetSlider. A description of
each follows:
void DwtScrollBarGetSlider (widget, value_return, shown_return,

inc_return, page inc_return)
Widget widget;
int * value_return;
int * shown_return;
int *inc_return;
int * pageinc_return;

widget

Specifies the scroll bar widget ID.

value return

Returns the scroll bar's top thumb (slider) position between
the DwtNminValue and DwtNmaxValue attributes to
the scroll bar widget.

shown return

Returns the size of the slider as a value between zero and the
absolute value of DwtNmaxVal ue minus
DwtNminVal ue. The size of the slider varies, depending
on how much of the slider scroll area it represents.

Subarea Widget Functions 3-11

inc return

Returns the amount of button increment and decrement.

page inc_return Returns the amount of page increment and decrement.
void DwtScrollBarSetSlider (widget, value, shown, inc,

page_inc, notify )
Widget widget;
int value;
int shown;
int inc, page_inc;
Boolean notify;

widget
value

Specifies the scroll bar widget ID.
Specifies the scroll bar's top thumb (slider) position between
DwtNrninValue and DwtNrnaxValue. The attribute
name associated with this argument is DwtNval ue.

shown

Specifies the size of the slider as a value between zero and
the absolute value of DwtNrnaxVal ue minus
DwtNrninValue. The size of the slider varies, depending
on how much of the slider scroll area it represents. This
argument sets the DwtNshown attribute associated with
DwtScrollBarCreate.

inc

Specifies the amount of button increment and decrement. If
this argument is nonzero, the scroll bar widget automatically
adjusts the slider when an increment or decrement action
occurs. This argument sets the DwtNinc attribute
associated with DwtScrollBarCreate.

page_inc

Specifies the amount of page increment and decrement. If
this argument is nonzero, the scroll bar widget automatically
adjusts the slider when an increment or decrement action
occurs. This argument sets the DwtNpagelnc attribute
associated with DwtScrollBarCreate.

notify

Specifies a boolean value that, when True, indicates a
change in the scroll bar value and that the scroll bar widget
automatically activates the
DwtNvalueChangedCallback with the recent change.
If False, no change in the scroll bar's value has occurred
and DwtNval ueChangedCallback is not activated.

The DwtScrollBarSetSlider function sets or changes the currently
displayed scroll bar widget slider for the application. The
DwtScrollBarGetSlider function returns the currently displayed
size/position values of the slider in the scroll bar widget.

3-12 Subarea Widget Functions

The scroll region is overlaid with a slider bar that is adjusted in size and
position using the main scroll bar or set slider function attributes. The
stepping arrows and the slider are the scroll activator objects providing the
user interface syntax "feeL"

3.3 Creating a Label Widget
You use labels to identify some types of controls. Labels consist of text or
graphics, or both, and describe a control or set of controls. For information
on using controls and labels, see the XUI Style Guide. To create an instance
of the label widget, use DwtLabelor DwtLabelCreate. When calling
DwtLabel, you set the label widget attributes presented in the formal
parameter list. For DwtLabelCreate, however, you specify a list of
attribute name/value pairs that represent all the possible label widget
attributes. After you create an instance of this widget, you can manipulate it
using the appropriate X intrinsics functions. A description of each follows:
Widget DwtLabel (parent_widget, name, x, y, label, help_callback)
Widget parent_widget;
char * name ;
Position x, y;
DwtCornpString label;
DwtCallbackPtr help_callback;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

label

Specifies the label for the text style. This argument sets the
DwtNlabel attribute associated with DwtLabelCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.

Subarea Widget Functions 3-13

Widget DwtLabelCreate (parent_widget, name,

override_arglist, override_argcount)
Widget parent_widget;
char * name;
ArgLi st override_arglist ;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Because a label widget does not support children, it always refuses geometry
requests. The label widget does nothing on a resize by its parents.
The following sections discuss these aspects of the label widget:

3.3.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRHelpRequested

The user selected Help.

XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding.

3.3.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the label widget is:
•
•

core
composite

•

common

•
label
Based on this class hierarchy, the label widget inherits attributes from the
core, composite, and common widgets. Table 3-3 lists the attributes inherited
by the label widget. For descriptions of the core and common attributes, see
Chapter 1.

Table 3-3: Attributes Inherited by the Label Widget
Attribute Name

Data Type

Default

DwtNx

position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators

XtTranslations

Determined by the geometry
manager
Determined by the geometry
manager
The width of the label or pixmap,
plus two times
DwtNmarginWidth
The height of the label or pixmap,
plus two times
DwtNmarginHeight
zero pixels
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget'S DwtNsensitive and
DwtNancestorSensitive
attributes
NULL

Core Attributes

Subarea Widget Functions 3-15

Table 3-3:

(continued)

Attribute Name

Data Type

Default

DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

3.3.3

Widget-Specific Attributes
Table 3-4 lists the widget-specific attributes for the label widget.
Descriptions of these attributes follow the table.

Table 3-4: Widget-Specific Attributes for the Label Widget
Attribute Name

Data Type

Default

DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap
Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter
NULL
Zero
Zero
Zero
Zero

3-16 Subarea Widget Functions

Table 3-4:

(continued)

Attribute Name

Data Type

Default

DwtNconformToText

Boolean

True, if the widget is created
with a width and height of zero
False, if the widget is created
with a non-zero width and height

DwtNlabelType

Specifies the label type. You can pass
DwtCString (compound string) or DwtPixmap
(icon data in pixmap).

DwtNlabel

Specifies the label for the text style.

DwtNmarginWidth Specifies the number of pixels between the border of
the widget window and the label.
DwtNmarginHeight Specifies the number of pixels between the border of
the widget window and the label.
DwtNalignment

Specifies the label alignment for text style. You can
pass DwtAlignmentCenter (center alignment),
DwtAlignmentBeginning (alignment at the
beginning), or DwtAlignmentEnd (alignment at
the end).

DwtNpixmap

Supplies icon data for the label. Pixmap is used
when DwtNlabel Type is defined as
DwtNpixmap.

DwtNmarginLeft

Specifies the number of pixels that are to remain
inside the left margin (DwtNmarginWidth) of the
widget before the label is drawn.

DwtNmarginRight Specifies the number of pixels that are to remain
inside the right margin (DwtNmarginWidth) of
the widget before the label is drawn.
DwtNmarginTop

Specifies the number of pixels that are to remain
inside the top margin (DwtNmarginTop) of the
widget before the label is drawn.

DwtNmarginBottom Specifies the number of pixels that are to remain
inside the bottom margin (DwtNmarginTop) of the
widget before the label is drawn.
DwtNconformToTextSpecifies a boolean value that indicates whether or
not the widget always attempts to be just big enough
to contain the label. If True, an XtSetValues
with a new label string causes the widget to attempt

Subarea Widget Functions 3-17

to shrink or expand to fit exactly (accounting for
margins) the new label string. Note that the results
of the attempted resize are up to the geometry
manager involved. If False, the widget never
attempts to change size on its own.

3.4 Creating a Toggle Button Widget
A toggle button is a control that can be set in either the on or off position.
An individual toggle button consists of a square indicator to the left of or
above the button name. When the user moves the mouse pointer onto the
toggle button and clicks MB 1, the button's state changes to the opposite of
what it was. An empty square indicates that the toggle button is off; a filled
square indicates that it is on.
To create an instance of the toggle button widget, use Dwt ToggleBut ton
or DwtToggleButtonCreate. When calling DwtToggleButton,
you set the common toggle button widget attributes presented in the formal
parameter list. For DwtToggleButtonCreate, however, you specify a
list of attribute name/value pairs that represent all the possible toggle button
widget attributes. After you create an instance of this widget, you can
manipulate it using the appropriate X intrinsics functions. A description of
each follows:
Widget DwtToggleButton (parent_widget, name, x, y,
label, value, callback, help_callback)
Widget parent_widget;
char * name ;
Position x, y;
DwtCornpString label;
Boolean value;
DwtCallbackPtr callback;
DwtCallbackPtr help_callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

3-18 Subarea Widget Functions

label

Specifies the text in the toggle button label/indicator. This
argument sets the DwtNlabel attribute associated with
DwtLabelCreate.

value

Specifies a boolean value that, when Fa 1 s e, indicates the
button state is off. If True, the button state is on. This
argument sets the DwtNval ue attribute associated with
DwtToggleButtonCreate.

callback

Specifies the callback function or functions called back when
the value of the toggle button changes. This argument sets
the DwtNarmCallback, DwtNdisarmCallback,and
DwtNvalueChangedCallback attributes associated with
DwtToggleButtonCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.

Widget DwtToggleButtonCreate (parent_widget, name,
override_arglist , override_ argcount)
Widget parent_widget;
char * name ;
ArgList override_arglist;
int override_ argcount ;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_ arg list Specifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _ arglist).

The DwtToggleButton and DwtToggleButtonCreate functions
create an instance of a toggle button widget and return its associated widget
ID.
The toggle button widget consists of either a label and indicator button
combination or simply a pixmap (icon). Toggle buttons imply an on or off
state. These functions use their attributes to configure the visual
representation, "looks," and the user interface syntax "feel," for the
application. Note that the callback data structure includes a value member,
which allows the callback data function to pass the status of the toggle switch
back to the application.
The following sections discuss these aspects of the toggle button widget:
•

Callback information

Subarea Widget Functions 3-19

3.4.1

•

Geometry management and resizing

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
int value;
DwtTogglebuttonCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRVal ueChanged

The user activated the toggle button to
change state.

Dwt CRArm

The user armed the toggle button by
pressing MB 1 while the pointer was inside
the toggle button widget.

DwtCRDisarm

The user disarmed the toggle button by
pressing MB 1 while the pointer was inside
the toggle button widget, but did not release
it until after moving the pointer outside the
toggle button widget.

DwtCRHelpRequested

The user selected Help.

3.4.2

Geometry Management and Resizing
The sizing is affected by these attributes: DwtNspacing, DwtNfont
(text label), and DwtNlabel. For more information, see DwtLabel and
DwtLabelCreate.

3-20 Subarea Widget Functions

The DwtNindicator size is based on the height of the toggle button
minus twice the margin height. The DwtNindicator width is equal to
the indicator height.
The default margin height is four pixels. The default margin width is five
pixels.

3.4.3

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the toggle button widget is:
•
•

core
composite

•

common

•

label

•

toggle

Based on this class hierarchy, the toggle button widget inherits attributes
from the core, composite, and common widgets. In addition, it inherits
attributes from the label widget. Note that you cannot set the attributes for
the composite widget; therefore, they are not shown.
Table 3-5 lists the attributes inherited by the toggle button widget. For
descriptions of the core and common attributes, see Chapter 1. For
descriptions of the label widget attributes, see Section 3.3.3.

Table 3-5: Attributes Inherited by the Toggle Button Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground

Dimension
Pixel
Pixmap
Pixel

Determined by the geometry
manager
Determined by the geometry
manager
Width of the label or pixmap,
plus three times
DwtNmarginWidth, plus the
width of DwtNindicator
The height of the label or pixmap,
plus two times
DwtNmarginHeight
zero pixels
Default foreground color
NULL
Default background color

Core Attributes

Subarea Widget Functions 3-21

Table 3-5:

(continued)

Attribute Name

Data Type

DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Default

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font

NULL

Label Attributes
DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap
Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter

NULL
Zero
Zero
Zero
Zero
True, if the widget is created
with a width and height of zero
False, if the widget is created
with a non-zero width and height

3-22 Subarea Widget Functions

3.4.4

Widget-Specific Attributes
Table 3-6 lists the widget-specific attributes for the toggle button widget.
Descriptions of these attributes follow the table.

Table 3-6: Widget-Specific Attributes for the Toggle Button
Widget
Attribute Name

Data Type

Default

DwtNshape
DwtNvisibleWhenOff
DwtNspacing
DwtNpixmapOn
DwtNpixmapOff
DwtNvalue
DwtNarmCallback
DwtNdisarmCallback
DwtNvalueChangedCallback
DwtNindicator

unsigned char
Boolean
short
Pixmap
Pixmap
Boolean
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
Boolean

DwtRectangular
True
4 pixels

DwtNacceleratorText
DwtNbuttonAccelerator
DwtNinsensitivePixmapOn
DwtNinsensitivePixmapOff

DwtCompString
char *
Pixmap
Pixmap

DwtNshape

NULL
NULL
False

NULL
NULL
NULL
True when the label is
DwtCString
False when the label is
DwtPixmap

NULL
NULL
NULL
NULL

Specifies the toggle button indicator shape. You can
pass DwtRectangular or DwtOval.

DwtNvisibleWhenOff

Specifies a boolean value that, when True,
indicates that the toggle button is visible when in the
off state.

Subarea Widget Functions 3-23

DwtNspacing

Specifies the number of pixels between the label and
the button if DwtNlabel Type is
DwtCornpString.

DwtNpixrnapOn

Specifies the pixmap to be used as the button label if
DwtNlabel Type is DwtP ixrnap and the toggle
button is in the on state.

DwtNpixrnapOff

Specifies the pixmap to be used as the button label if
DwtNlabel Type is DwtP ixmap and the toggle
button is in the off state.

DwtNvalue

Specifies a boolean value that, when False,
indicates the button state is off. If True, the button
state is on.

DwtNarrnCallback Specifies the callback function or functions called
when the toggle button is armed. The toggle button
is armed when the user presses and releases MB 1
while the pointer is inside the toggle button widget.
For this callback, the reason is Dwt CRArrn.
DwtNdisarrnCallback
Specifies the callback function or functions called
when the button is disarmed. The button is disarmed
when the user presses MB 1 while the pointer is
inside the toggle button widget, but moves the
pointer outside the toggle button before releasing
MB 1. For this callback, the reason is
DwtCRDi sarrn.
DwtNvalueChangedCallback
Specifies the callback function or functions called
when the toggle button value was changed. For this
callback, the reason is DwtCRVal ueChanged.
DwtNindicator

Specifies a boolean value that, when True, signifies
that the indicator is present in the toggle button. If
Fa 1 s e, signifies that the indicator is not present in
the toggle button.

DwtNacceleratorText
Specifies the compound-string text displayed for the
accelerator.
DwtNbuttonAccelerator
Sets an accelerator on a toggle button widget.
DwtNinsensitivePixrnapOn
Specifies the pixmap used when the toggle button is
on and is insensitive. This attribute applies only if

3-24 Subarea Widget Functions

the toggle button label is specified as a pixmap.
DwtNinsensitivePixmapOff

Specifies the pixmap used when the toggle button is
off and is insensitive. This attribute applies only if
the toggle button label is specified as a pixmap.

3.5 Obtaining and Setting the Toggle Button Widget
State
The toggle button widget has two states: on or off. There may be occasions
when your application needs to know the current state of the toggle button.
There may be other times when your application needs to change or set the
current state of the toggle button. To obtain the state of the toggle button,
use Dwt ToggleButtonGetState. To set or change the toggle button's
current state, use DwtToggleButtonSetState. A description of each
follows:
Boolean DwtToggleButtonGetState (widget)
Widget widget;

widget

Specifies the widget ID.

void DwtToggleButtonSetState (widget, value, notify)
Widget widget;
Boolean value;
Boolean notify;

widget

Specifies the widget ID.

value

Specifies a boolean value that, when False, indicates the
button state is off. If T ru e, the button state is on. This
argument sets· the DwtNvalue attribute associated with
DwtToggleButtonCreate.

notify

Specifies a boolean value that, when True, indicates a
recent change in the on/off state of the toggle button and
DwtNvalueChangedCallback should be activated with
the recent change. If False, no change in state has
occurred and DwtNvalueChangedCallback should not
be activated.

The DwtToggleButtonGetState function returns the current state
(value) of the toggle button, either True (on) or False (off).
The Dwt ToggleButtonSetState function sets or changes the toggle
button's current state (value) within the display.

Subarea Widget Functions 3-25

3.6 Creating a Radio Box Widget
Your application may require multiple toggle buttons. You can use the radio
box widget to hold multiple toggle button widgets. To create an msta..l1ce of
the radio box widget, use DwtRadioBox or DwtRadioBoxCreate.
When calling DwtRadioBox, you set the radio box widget attributes
presented in the formal parameter list. For DwtRadioBoxCreate,
however, you specify a list of attribute name/value pairs that represent all the
possible radio box widget attributes. After you create an instance of this
widget, you can manipulate it using the appropriate X intrinsics functions. A
description of each follows:
Widget DwtRadioBox (parent_widget, name, x, y,
entry_callback, help_callback)
Widget parent_widget;
char * name ;
Position x, y;
DwtCallbackPtr entry_callback, help_callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left corner of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

entry_callback If this callback is defined, all menu entry activation callbacks
are revectored to call back through this callback. If this
callback is NULL, the individual menu entry callbacks work
as usual. For this callback, the reason is
DwtCRActi vate. This argument sets the
DwtNentryCallback attribute associated with
DwtMenuCreate.
help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.

3-26 Subarea Widget Functions

Widget DwtRadioBoxCreate (parent widget, name,
override_arglist , override_ argcount)
Widget parent_widget;
char * name ;
ArgList override_arglist;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

3.6.1

•

Callback information

•

Widget class hierarchy and inherited attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
Widget s_widget;
char *s_tag;
char *s_callbackstructi
DwtRadioBoxCallbackStructi

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRValueChanged

The user activated the toggle button to
change state.

Subarea Widget Functions 3-27

DwtCRMap

The radio box is about to be mapped.

DwtCRHelpRequested

The user selected Help.

The event member is a pointer to the Xlib structure XEvent, which
describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the. Guide to the Xlib Library: C
Language Binding. The s_widget member is set to the ID of the activating
subwidget. The s_tag member is set to the tag supplied by the application
programmer when the subwidget callback function was specified. The
s_callbackstruct member is set to the subwidget's callback structure.

3.6.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the radio box widget is:
•
•

core
composite

•

common

•
•

menu
radio box

Based on this class hierarchy, the radio box widget inherits attributes from
the core, composite, common, and menu widgets. Note that you cannot set
the attributes for the composite widget; therefore, they are not shown.
Table 3-7 lists the attributes inherited by the radio box widget. For
descriptions of the core and common attributes, see Chapter 1. For
descriptions of the menu widget attributes, see Section 4.1.1.4.

Table 3-7: Attributes Inherited by the Radio Box Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

Detennined by the geometry
manager
Detennined by the geometry
manager
Set as large as necessary to hold
all child widgets

Core Attributes

3-28 Subarea Widget Functions

Table 3-7:

(continued)

Attribute Name

Data Type

Default

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Set as large as necessary to hold
all child widgets
One pixel
Default foreground color

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr

Default foreground color
Default foreground color

NULL
Default background color

NULL
Default color map
True
Setting the sensitivity of the radio
box causes all widgets contained
in that radio box to be set to the
same sensitivity.
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font

NULL

Menu Attributes
DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder

Dimension
Dimension
Dimension
unsigned char
Boolean
short

Zero pixels
3 pixels
Three pixels
DwtOrientationVertical
True
Zero pixels

Subarea Widget Functions 3-29

Table 3-7:

(continued)

Attribute Name

Data Type

Default

DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

Boolean
unsigned char
unsigned char

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

Widget
DwtCallbackPtr
Widget
Boolean
Boolean

True
DwtAlignmentBeginning
DwtMenuPackingTight(fur
all menu types except for radio
boxes)
DwtMenuPackingColumn(fur
radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)
NULL
Radio boxes, however, default to
the togglebuttonwidgetclass.
Zero
NULL
NULL
True
True

3.7 Creating a Push Button Widget
A push button consists of a name or an icon within a rectangular frame.
When the user clicks MB 1 anywhere on a push button, the action described
by the label is initiated. For more information on push buttons, see the XUI
Style Guide.
To create an instance of the push button widget, use DwtPushButton or
DwtPushButtonCreate. When calling DwtPushButton, you set the
push button widget attributes presented in the formal parameter list. For
DwtPushButtonCreate, however, you specify a list of attribute
name/value pairs that represent all the possible push button widget attributes.
After you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions. A description of each follows:

3-30 Subarea Widget Functions

Widget DwtPushButton (parent_widget, name, x, y,
label, callback, help_callback)
Widget parent_widget;
char *name;
Position x, y;
DwtCompString label;
DwtCallbackPtr callback, help_callback;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

label

Specifies the push button label. This argument sets the
DwtNlabel attribute associated with DwtLabelCreate.

callback

Specifies the callback function or functions called back when
a push button is activated. This argument sets the
DwtNactivateCallback, DwtNarmCallback,and
DwtNdisarmCallback attributes associated with
DwtPushButtonCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.

Widget DwtPushButtonCreate (parent_widget, name,
override_arg list, override_argcount)
Widget parent_widget;
char * name ;
ArgLi st override arglist;
int override_argcount ;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

Subarea Widget Functions 3-31

The DwtPushButton and DwtPushButtonCreate functions create an
instance of the push button widget and return its associated widget ID. The
push button is a primitive widget that displays a rectangular border around a
label. The label defines the immediate action of the button (for exanlple, Ok
or Cancel in a dialog box).
The sizing is affected by spacing, font (affects indicator), and label. The
push button widget follows the same rules for geometry management as its
superclass the label widget, which you create by calling DwtLabel or
DwtLabelCreate. Like the label widget, the push button widget does not
support children; therefore, it always refuses geometry requests.
The push button widget follows the same rules for resizing as its superclass
the label widget, which you create by calling DwtLabelor
DwtLabelCreate. Like the label widget, the push button widget does
nothing on a resize by its parents. The following sections discuss these
aspects of the push button widget:

3.7.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActivate

The user activated the push button by
pressing MB 1 while the pointer was inside
the push button widget.

DwtCRArm

The user armed the push button by pressing
MB 1 while the pointer was inside the push
button widget.

3-32 Subarea Widget Functions

DwtCRDisarm

The user disarmed the push button in one of
two ways. The user pressed MB 1 while the
pointer was inside the push button widget,
but did not release it until after moving the
pointer outside the push button widget. Or,
the user activated the push button, which
also disarms it.

DwtCRHelpRequested

The user selected Help.

3.7.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the push button widget is:
•
•

core
composite

•

common

•
•

label
push button

Based on this class hierarchy, the push button widget inherits attributes from
the core, composite, and common widgets. In addition, it inherits attributes
from the label widget. Note that you cannot set the attributes for the
composite widget; therefore, they are not shown.
Table 3-8 lists the attributes inherited by the push button widget. For
descriptions of the core and common attributes, see Chapter 1. For
descriptions of the label widget attributes, see Section 3.3.3.

Table 3-8: Attributes Inherited by the Push Button Widget
Attribute Name

Data Type

Default

Position

Determined by the geometry
manager

Core Attributes
DwtNx

Subarea Widget Functions 3-33

Table 3-8:

(continued)

Attribute Name

Data Type

Default

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Determined by the geometry
manager
The width of the label or pixmap
plus DwtNmarginWidth times
two
The height of the label or pixmap
plus DwtNmarginHeight
times two
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensi ti ve and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

unsigned char
DwtCompString
Dimension

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback
Label Attributes
DwtNlabelType
DwtNlabel
DwtNmarginWidth

3-34 Subarea Widget Functions

Table 3-8:

3.7.3

(continued)

Attribute Name

Data Type

Default

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter
NULL
Zero
Zero
Zero
Zero
True, if the widget is created
with a width and height of zero
Fa 1 s e, if the widget is created
with a non-zero width and height

Widget-Specific Attributes
Table 3-9 lists the widget-specific attributes for the push button widget.
Descriptions of these attributes follow the table.

Table 3-9: Widget-Specific Attributes for the Push Button Widget
Attribute Name

Data Type

Default

DwtNbordHighlight
DwtNfillHighlight
DwtNshadow
DwtNactivateCallback
DwtNarmCallback
DwtNdisarmCallback
DwtNacceleratorText
DwtNbuttonAccelerator
DwtNinsensitivePixmap

Boolean
Boolean
Boolean
DwtCallbackptr
DwtCallbackptr
DwtCallbackptr
DwtCompString
char *
Pixmap

False
False
True
NULL
NULL
NULL
NULL
NULL
NULL

DwtNbordHighlightSpecifies a boolean value that, when True,
highlights the border.
DwtNfillHighlightSpecifies a boolean value that, when True, fills the
highlighted button.

Subarea Widget Functions 3-35

DwtNshadow

Specifies whether the shadow of the push button is
displayed.

DwtNactivateCallback
Specifies the callback function or functions called
when the push button is activated. The button is
activated when the user presses and releases MB 1
while the pointer is inside the push button widget.
Activating the push button also disarms the push
button. For this callback, the reason. is
DwtCRActi vate.
DwtNarmCallback Specifies the callback function or functions called
when the push button is armed. The push button is
armed when the user presses and releases MB 1 while
the pointer is inside the push button widget. For this
callback, the reason is Dwt CRArm.
DwtNdisarmCallback
Specifies the callback function or functions called
when the push button is disarmed. The button is
disarmed in two ways. After the user activates the
button (presses and releases MB 1 while the pointer is
inside the push button widget), the button is
disarmed. When the user presses MB 1 while the
pointer is inside the push button widget but moves
the pointer outside the push button before releasing
MB 1, the button is disarmed. For this callback, the
reason is Dwt CRD is arm.
DwtNacceleratorText
Specifies the compound-string text displayed for the
accelerator.
DwtNbuttonAccelerator
Sets an accelerator on a push button widget. This is
the same as the DwtNtranslations core
attribute except that only the left side of the table is
to be passed as a character string, not compiled. The
application is responsible for calling
XtInstallAllAccelerators to install the
accelerator where the application needs it.
DwtNinsensitivePixmap
Specifies the pixmap used when the push button is
set to insensitive. This attribute applies only if the
push button label is specified as a pixmap.

3-36 Subarea Widget Functions

3.8 Creating a Scale Widget
A scale allows the user to enter a value from a range of values by adjusting
an arrow to a specific position along a line. Each scale consists of a label
and the following elements:
•

A line, with tick marks, that represents the range of the scale from n to

m.
•

An arrow that is the analog representation of the currently chosen scale
value.

•

An optional number directly opposite the arrow that is the digital
representation of the currently selected scale value.

For information on designing scales, see the XUI Style Guide.
To create an instance of the scale widget, use DwtScale or
DwtScaleCreate. When calling DwtScale, you set the scale widget
attributes presented in the formal parameter list. For DwtScaleCreate,
however, you specify a list of attribute name/value pairs that represent all the
possible scale widget attributes. After you create an instance of this widget,
you can manipulate it using the appropriate X intrinsics functions. A
description of each follows:
Widget DwtScale (parent_widget, name, x, y,

width, height, scale_width, scale_height,
title, min_value, max_value, decimalyoints,
value, orientation, callback,
drag_callback, help_callback)
Widget parent_widget;
char * name;
Position x, y;
Dimension width, height;
Dimension scale_width, scale_height;
DwtCompString title;
int min_value, max_value;
int decimalyoints;
int value;
unsigned char orientation;
DwtCallbackPtr callback, drag_callback, help_callback;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Subarea Widget Functions 3-37

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

width

Specifies the width of the widget window. (The window
width is calculated based on the scale width, the label widths,
and orientation.) This argument sets the DwtNwidth core
widget attribute.

height

Specifies the height of the widget window. (The window
height is calculated based on the scale height, the labels, and
orientation.) This argument sets the DwtNheight core
widget attribute.

scale width

Specifies the width of the scale, excluding the scale labels.
This argument sets the DwtNscaleWidth attribute
associated with DwtScaleCreate.

scale_height

Specifies the height of the scale, excluding the scale labels.
This argument sets the DwtNscaleHeight attribute
associated with DwtScaleCreate.

title

Specifies the title text string to appear in the scale window
widget. This argument sets the DwtNt it 1 e attribute
associated with DwtScaleCreate.

min value

Specifies the value represented by the top or left end of the
scale. This argument sets the DwtNminVal ue attribute
associated with DwtScaleCreate.

max value

Specifies the value represented by the bottom or right end of
the scale. This argument sets the DwtNmaxVal ue attribute
associated with DwtScaleCreate.

decimalyoints Specifies the number of decimal points to shift the current
slider value for display of the next slider position. This
argument sets the DwtNdecimalPoints attribute
associated with DwtScaleCreate.
value

Specifies the current slider position along the scale (the value
selected by the user). This argument sets the DwtNvalue
attribute associated with DwtScaleCreate.

orientation

Specifies whether the scale is displayed vertically or
horizontally. You can pass
DwtOrientationHorizontalor
DwtOrientationVertical. This argument sets the
DwtNorientation attribute associated with
DwtScaleCreate.

3-38 Subarea Widget Functions

callback

Specifies the callback function or functions called back when
the value of the scale changes. This argument sets the
DwtNvalueChangedCallback attribute associated with
DwtScaleCreate.

drag_callback Specifies the callback function or functions called when the
user is dragging the scale slider. For this callback, the reason
is Dwt CRD rag. This argument sets the
DwtNdragCallback attribute associated with
DwtScaleCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtScaleCreate (parent widget, name,

override_argUst, override_argcount)
Widget parent_widget;
char * name ;
ArgLi st override_ argUst ;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _ argUst).

The DwtScale and DwtScaleCreate functions create an instance of
the scale widget and return its associated widget ID. The scale widget is a
primitive widget figure that allows the application to display a scale for
vernier control of a specific parameter by the user. The user moves or drags
a slider, which is part of the scale widget, and places the slider at a position
representing the desired value. The scale may have labeled text at any
number of points identifying the values corresponding to the points. The
scale can be made insensitive and used as an output value indicator only (for
example, a thermometer or percent completion indicator).
The application passes lower and upper values for the scale as integers and
can (optionally) indicate a decimal point position. For example, a
DwtNminVal ue of 100, a DwtNmaxVal ue of 10000, and a
DwtNdecimalPoints of 2 would produce a scale from 1.00 to 100.00.
Possible values returned from this example could be 230 or 5783.
Scale widget labels are provided by its children. The labels can be any
widgets created using the scale widget as the parent.

Subarea Widget Functions 3-39

The following sections discuss these aspects of the scale widget:

3.8.1

•

Callback structure infonnation

•

Geometry management and resizing

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
int value;
DwtScaleCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRVal ueChanged

The user moved the slider in the scale with
drag or click.

DwtCRDrag

The user is dragging the slider.

DwtCRHelpRequested

The user selected Help.

3.8.2

Geometry Management and Resizing
The scale widget moves its children so that they will be within the scale
widget's calculated size. It is recommended that you create the scale widget
with as many of the dimension-type attributes set to zero as possible. This
allows the scale widget to make the best decisions for its layout.

If told to resize, the scale widget positions its children so they all fit within
the scale widget.

3-40 Subarea Widget Functions

3.8.3

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the scale widget is:
•
•

core
composite

•

common

•
scale
Based on this class hierarchy, the scale widget inherits attributes from the
core, composite, and common widgets. Note that you cannot set the
attributes for the composite widget; therefore, they are not shown.
Table 3-10 lists the attributes inherited by the scale widget. For descriptions
of the core and common attributes, see Chapter 1.

Table 3-10: Attributes Inherited by the Scale Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged

XtTranslations
int
XtTranslations
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Calculated based on scale width,
the label widths, and the
orientation
Calculated based on scale height,
the label widths, and the
orientation
zero pixels
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True

Attribute Name

Core Attributes

Subarea Widget Functions 3-41

Table 3-10:

(continued)

Attribute Name

Data Type

Default

DwtNscreen
DwtNdestroyCallback

Screen *
DwtCallbackPtr

The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

3.8.4

Widget-Specific Attributes
Table 3-11 lists the widget-specific attributes for the scale widget.
Descriptions of these attributes follow the table.

Table 3-11: Widget-Specific Attributes for the Scale Widget
Attribute Name

Data Type

Default

DwtNvalue
DwtNtitle
DwtNorientation
DwtNscaleWidth
DwtNscaleHeight
DwtNminValue
DwtNmaxValue
DwtNdecimalPoints
DwtNshowValue
DwtNdragCallback
DwtNvalueChangedCallback

int
DwtCompString
unsigned char
Dimension
Dimension
int
int
short
Boolean
DwtCallbackptr
DwtCallbackPtr

zero
Scale name
DwtOrientationHorizonta
100 pixels
20 pixels
Zero
100
Zero
True
NULL
NULL

DwtNvalue

3-42 Subarea Widget Functions

Specifies the current slider position along the scale
(the value selected by the user).

DwtNtitleType

Specifies the title type. You can pass
DwtCString or DwtPixmap.

DwtNtitle

Specifies the title text string to appear in the scale
window widget.

DwtNorientation Specifies whether the scale is displayed vertically or
horizontally . You can pass
DwtOrientationHorizontalor
DwtOrientationVertical.
DwtNscaleWidth

Specifies the thickness in pixels of the scale itself,
not counting the labels.

DwtNscaleHeight Specifies the height of the scale, excluding the scale
labels.
DwtNminValue

Specifies the value represented by the top or left end
of the scale.

DwtNmaxValue

Specifies the value represented by the bottom or right
end of the scale.

DwtNdecimalPointsSpecifies the number of decimal points to shift the
current slider value for display of the next slider
position.
DwtNshowValue

Specifies a boolean value that, when True, states
that the current value of the slider label string will be
displayed next to the slider.

DwtNdragCallback Specifies the callback function or functions called
when the user is dragging the scale slider. For this
callback, the reason is DwtCRDrag.
DwtNvalueChangedCallback
Specifies the callback function or functions called
when the scale value was changed. For this callback,
the reason is DwtCRValueChanged.

3.9 Obtaining and Setting the Scale Slider Position
The scale widget allows the user to enter a value from a range of values.
There may be occasions when your application needs to know the current
value of the scale. There may be other times when your application needs to
change or set the current value of the scale. To obtain the current slider
position value, use DwtScaleGetSlider. To set or change the current
value of the slider position, use DwtScaleSetSlider. A description of
each follows:

Subarea Widget Functions 3-43

void DwtScaleGetSlider (widget, value _return)
Widget widget i
int * value_return i

widget

Specifies the scale widget ID.

value return

Returns the current slider position value.

void DwtScaleSetSlider (widget, value)
Widget widget i
int value i

widget

Specifies the scale widget ID.

value

Specifies the current slider position along the scale (the value
selected by the user). This argument sets the DwtNval ue
attribute associated with DwtScaleCreate.

The DwtScaleGetSlider function returns the current slider position
value displayed in the scale for the application.
The DwtScaleSetSlider function sets or changes the current slider
position value within the scale widget display for the application.

3-44 Subarea Widget Functions

Menu Widget Functions

A menu is a window that consists of a name and a list of choices. Menus
provide the user with pointer cursor access to the tasks in your application.
This chapter discusses the functions you can use to create a:
•

Menu (pull-down, pop-up, and menu work area) widget

•

Pull-down menu entry widget

•

Option menu widget

•

Separator widget

In addition, the chapter discusses some menu convenience functions you can
use to position the menu when the user presses MB2 and to highlight a menu
entry.
For information on menu items and for a discussion on designing and
displaying the different types of menus, see the XU] Style Guide. For a
discussion of the function used to create an instance of the menu bar widget,
see Chapter 2.

4.1

Creating Menu Widgets
There are three types of menus:
•

Pull-down
A pull-down menu is the only type of menu that has a menu name. The
menu-name should clearly indicate the purpose of the items in the
menu. Each menu name displayed in the menu bar must be unique.

•

Submenu
A submenu is a menu that is invoked from a menu. A menu item that
invokes a submenu cannot have an accelerator; menu items within a
submenu, however, can have accelerators.

•

Pop-up
A pop-up menu is a menu that appears at the current pointer position.
The contents of pop-up menus change with the location of the pointer
cursor and the current selection. Pop-up menus contain items that can
also be invoked through other mechanisms, such as pull-down menus
and permanent dialog boxes. They serve as a user short-cut by reducing
mouse movement.

The following are ways to create instances of the pull-down, pop-up, and
menu work area widgets:
•

Pull-down, pop-up, and menu work area widgets
Call DwtMenu and pass the appropriate constant to indicate whether
the menu is a pull-down, pop-up, or work area menu.

•

Menu work area widget
Call DwtMenuCreate.

•

Pull-down menu widget
Call DwtMenuPulldownCreate.

•

Pop-up menu widget
Call DwtMenuPopupCreate.

These functions are discussed in the following sections.

4.1.1

Creating Pull-Down, Pop-Up, and Menu Work Area Widgets
To create an instance of the pull-down, pop-up, and menu work area widgets,
use DwtMenu. You can also use DwtMenuPulldownCreate to create
an instance of the pull-down menu widget; DwtMenuPopupCreate to
create an instance of the pop-up menu widget; and DwtMenuCreate to
create an instance of the menu work area widget. When calling DwtMenu,
you set the menu widget attributes presented in the formal parameter list.
One of these attributes allows you to specify the type of menu widget
instance you want to create: pop-up, pull-down, or menu work area. For
DwtMenuCreate, DwtMenuPulldownCreate,and
DwtMenuPopupCreate, however, you specify a list of attribute
name/value pairs that represent all the possible menu widget attributes. After
you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions.
A description of each follows:
Widget DwtMenu (parent_widget, name, x, y, format,
orientation, entry_callback, map_callback,
help_callback)
Widget parent_widget i
char * name i
Position x, Yi
int format i
unsigned char orientation i
DwtCallbackptr entry callback i
DwtCallbackptr map callback i
DwtCallbackPtr help_callback;

4-2 Menu Widget Functions

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.
Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

format

Specifies the type of menu widget. You can pass
DwtMenuPopup, DwtMenuPulldown, or
DwtMenuWorkArea.

orientation

Specifies whether the menu list is vertical or horizontal. You
can pass DwtOrientationHorizontalor
DwtOrientationVertical. This argument sets the
DwtNorientation attribute associated with
DwtMenuCreate.

entry_callback If this callback is defined, all menu entry activation callbacks
are revectored to call back through this callback. If this
callback is NULL, the individual menu entry callbacks work
as usual. For this callback, the reason is
Dwt CRAct iva t e. This argument sets the
DwtNentryCallback attribute associated with
DwtMenuCreate.
map_ callback Specifies the callback function or functions called when the
window is about to be mapped. For this callback, the reason
is DwtCRMap. The map_callback argument is supported
only ifformat is DwtMenuPopup or
DwtMenuPulldown. The map_callback argument is
ignored if format is DwtMenuWorkArea.

This argument sets the DwtNmapCallback attribute
associated with DwtMenuCreate.
help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.

Menu Widget Functions 4-3

Widget DwtMenuCreate (parent_widget, name,
override_arglist, override_ argcount)
Widget parent_widget;
char * name ;
ArgLi st override arglist;
int override_argcount;
Widget DwtMenuPulldownCreate (parent_widget, name,
override_arglist,
override_argcount)
Widget parent_widget;
char * name;
ArgList override arglist;
int override_argcount;
Widget DwtMenuPopupCreate (parent_widget, name,
override_arglist , override_argcount)
Widget parent_widget;
char * name;
ArgLi st override arglist;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtMenu and DwtMenuCreate functions create an instance of a
menu widget and return its associated widget ID. The
DwtMenuPulldownCreate function creates an instance of a pull-down
menu widget and returns its associated widget ID. The
DwtMenuPopupCreate function creates an instance of a pop-up menu
widget and returns its associated widget ID.
A menu is a composite widget that contains other widgets (push buttons,
pull-down menus, toggle buttons, labels, and separators). The subwidgets
handle most I/O that display information and query the user for input. The
menu widget provides no input semantics over and above the semantics of its
subwidgets. The menu widget works with these widget subclasses: push
buttons, toggle buttons, pull-down menu entries, labels, and separators. If
DwtNentryCallback is non-NULL when activated, all subwidgets call
back to this callback. Otherwise, the individual subwidgets handle the
activated callbacks.

4-4 Menu Widget Functions

The following sections discuss these aspects of the menu widget:

4.1.1.1

•

Callback information

•
•

Geometry management and resizing
Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information - The following structure is returned to your
callback:
typedef struct {
int reason;
XEvent *event;
Widget s_widget;
char *s_tag;
char *s_callbackstruct;
DwtMenuCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActi vate

The user selected a menu entry.

DwtCRMap

The menu window is about to be mapped.

DwtCRUnmap

The menu window was just unmapped.

DwtCRHelpRequested

The user selected help.

4.1.1.2

Geometry Management and Resizing - In general, a menu enforces
positions, dimensions, and border widths for all children. In a vertical menu,
entries have uniform widths - the width of the widest item in the current
column. The height of each entry is not affected and is the responsibility of
the item itself. In a horizontal menu, on the other hand, items have uniform
height; the width is not affected.

Menu Widget Functions 4-5

In all menu packing modes except DwtNmenuPackingNone, the position
of an item is completely determined by the menu; the child widget has no
control of its position. In the DwtNmenuPackingNone packing mode,
the menu does not position items.
A menu complies with all geometry requests made by its children. The
menu determines the size needed to resize around its managed children and
then makes the request of its geometry manager. Even if the menu's parent
will not allow the request, the menu will. The child may then be clipped.
Height and width of a menu child are jointly controlled by the menu and the
child. If a child requests a larger size, the menu will honor the request and
then resize all other children to match. If a child requests a smaller size, the
menu will honor the request; however, the menu might make the child bigger
again shortly as the menu resizes the other children.
If DwtNentryUniformBorder is True, all entries will have exactly
the same border width. If DwtNentryUniformBorder is False, the
menu will not change any of the children's border widths.
When resized, the menu widget will layout all its managed children in
exactly the same manner as geometry management.

4.1.1.3

Widget Class Hierarchy and Inherited Attributes - The widget
class hierarchy for the menu widget is:
•
•

core
composite

•

common

•

The widget class hierarchy for the pull-down menu widget is:
•
•

core
composite

•

common

•
•

menu
menu pulldown

The widget class hierarchy for the pop-up menu widget is:
•
•

core
composite

•

common

4-6 Menu Widget Functions

•
•

menu
menu popup

Table 4-1 lists the attributes inherited by the menu widget. Table 4-2 lists
the attributes inherited by the pull-down For descriptions of the core and
common attributes, see Chapter 1. For descriptions of the menu widget
attributes, see Section 4.1.1.4.

Table 4-1: Attributes Inherited by the Menu Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
If menu orientation is
DwtOrientationVertical,
default is the maximum entry
DwtNwidth or 16 pixels.
If menu orientation is
DwtOrientationHorizontal,
default is the sum of
DwtNwidth and
DwtNspacing or 16 pixels.
If menu orientation is
DwtOrientationVertical,
default is the sum of
DwtNheight and
DwtNspacing or 16 pixels.
If menu orientation is
DwtOrientationHorizontal,
default is the maximum entry
DwtNheight or 16 pixels.
One pixel
Default foreground color

Core Attributes

NULL
Default background color

NULL
Default color map
True
Setting the sensitivity of the menu
causes all widgets contained in
that menu to be set to the same
sensitivity.

Menu Widget Functions 4-7

Table 4-1:

(continued)

Attribute Name

Data Type

Default

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Table 4-2: Attributes Inherited by the Pull-Down Menu and PopUp Menu Widgets
Data Type

Default

DwtNx

Position

DwtNy

position

For DwtMenuPopupCreate,
detennined by the geometry
manager
For
DwtMenuPulldownCreate,
this attribute is not supported
For DwtMenuPopupCreate,
detennined by the geometry
manager
For
DwtMenuPulldownCreate,
this attribute is not supported

Attribute Name
Core Attributes

4-8 Menu Widget Functions

Table 4-2:

(continued)

Attribute Name

Data Type

Default

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Set as large as necessary to hold
all child widgets
Set as large as necessary to hold
all child widgets
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char

Zero pixels
3 pixels
Three pixels
DwtOrientationVertical
True
Zero pixels
True
DwtAlignmentBeginning

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Menu Attributes
DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment

Menu Widget Functions 4-9

Table 4-2:

(continued)

Attribute Name

Data Type

Default

DwtNmenuPacking

unsigned char

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtMenuPackingTight(fur
all menu types except for radio
boxes)
DwtMenuPackingColumn(fur
radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

4.1.1.4

Widget
DwtCallbackptr
Widget
Boolean
Boolean

NULL

Radio boxes, however, default to
the togglebuttonwidgetc1ass.
Zero
NULL
NULL

True
True

Widget-Specific Attributes - Table 4-3 lists the widget-specific
attributes for the menu widget. Descriptions of these attributes follow the
table.
Table 4-3: Widget-Specific Attributes for the Menu Widget
Attribute Name

Data Type

Default

DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char
unsigned char

Zero pixels
3 pixels
Three pixels
DwtOrientationVertical
True
Zero pixels
True
DwtAlignmentBeginning
DwtMenuPackingTight(fur
all menu types except for radio
boxes)

4-10 Menu Widget Functions

Table 4-3:

(continued)

Attribute Name

Data Type

DwtNmenuNumCol umns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

Widget
DwtCallbackPtr
Widget
Boolean
Boolean

DwtNspacing

Default
DwtMenuPackingColumn (for
radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)
NULL
Radio boxes, however, default to
the togglebuttonwidgetclass.
Zero
NULL
NULL
True
True

Specifies in pixels the spacing between menu bar
entry windows.

DwtNmarginHeight Specifies the number of pixels remaining around the

entries. The height is the number of blank pixels
above the first entry and below the last entry (for
vertical menus).
DwtNmarginWidth Specifies the number of pixels remaining around the

entries. The width is the number of blank pixels
between the left and right edges of the menu and the
border of the entries.
DwtNorientation Specifies whether the menu list is vertical or

horizontal. You can pass
DwtOrientationHorizontalm
DwtOrientationVertical.
DwtNadjustMargin Specifies a boolean value that indicates whether the

inner minor dimension margins of all entries should
be set to the same value.
All label subclass widgets have two types of
margins. The two outer margins
(DwtNmarginWidth and DwtNmarginHeight)
are symmetrical about the center of the widget. The
number of pixels specified in DwtNmarginWidth

Menu Widget Functions 4-11

are blank to the right and the left of the widget. The
four inner margins (DwtNmarginLeft,
DwtNmarginRight, DwtNmarginTop,and
DwtNmarginBottom) specify the number of pixels
to leave on each side inside the outer margins.
The outer margins are used to accommodate such
things as the border highlighting of widgets. The
inner margins are used to accommodate such things
as pull-down widget hot spots and toggle button
indicators.
If True, all entries in a given column or row will
have exactly the same minor dimension margins. (If
DwtNorientationis
DwtOrientationHorizontal, the minor
dimension is vertical; if DwtNorientation is
DwtOrientationVertical, the minor
dimension is horizontal.) All margins will have the
value of the largest individual margin in the group.
This keeps the left edge of text lined up, regardless
of whether some entries have toggle indicators.

DwtNentryBorder Specifies the border width of windows on the entry
widgets.
DwtNmenuAlignmentSpecifies a boolean value that, when True,
indicates all entries are aligned. If Fa 1 s e, entry
alignment is unchanged. This is applied only to.
subclasses of labelwidgetclass.
DwtNentryAlignment
Specifies the type of label alignment that is enforced
for all entries when DwtNmenuAlignment is
True. You can pass DwtAlignmentCenter
(center alignment), DwtAlignmentBeginning
(alignment at the beginning), or
DwtAlignmentEnd (alignment at the end).
DwtNmenuPacking Specifies how to pack the entries of a menu into the
whole menu. The value of DwtNorientation
determines the major dimension. You can pass
DwtMenuPackingTight,
DwtMenuPackingColumn,or
DwtNmenuPackingNone.
DwtMenuPackingTight indicates that given the
current major dimension of the menu, entries are
placed one after the other until the menu must wrap.
When the menu wraps, it extends in the minor
4-12 Menu Widget Functions

dimension as many times as required.
Each entry's major dimension is left unaltered; its
minor dimension is set to the same value as the
greatest entry in that particular row or column. Note
that the minor dimension of any particular row or
column is independent of other rows or columns.
DwtMenuPackingColumn indicates that all
entries are placed in identically sized boxes. The box
is based on the size of the largest entry while the
value of DwtNmenuNumCol umns determines how
many boxes are placed in the major dimension before
extending in the minor dimension.
DwtNmenuP ackingNone indicates that no packing
is performed. The DwtNx and DwtNy attributes of
each entry are left alone and the menu attempts to
become large enough to enclose all entries.
DwtNmenuNumColumns

Specifies the number of minor dimension extensions
that will be made to accommodate the entries. This
attribute is used only if DwtNmenuP acking is set
~

DwtMenuPackingColumn.

For menus with an orientation of
DwtOrientationVertical, this attribute
indicates how many columns will be built. The
number of entries per column will be adjusted to
maintain this number of columns (if possible). For
menus with an orientation of
DwtOrientationHorizontal, this attribute
indicates how many rows will be built.
DwtNmenuRadio

Specifies a boolean value that, when True,
indicates that when one button is already on and
another button is turned on, the first button is turned
off automatically.

DwtNradioAlwaysOne

Specifies a boolean value that indicates if the radio
button exclusivity should also ensure that one button
must always be on. If True, when the only radio
button on is turned off, it will automatically be
turned back on. Note that this attribute has no effect
unless DwtNmenuRadio is True.
DwtNmenuIsHomogeneous

Specifies a boolean value that indicates if the menu

Menu Widget Functions 4-13

should enforce exact homogeneity among the
children of this menu. If True, only the
DwtNmenuEntryClass class (not subclass but
exact class) will be allowed as children of this menu.
DwtNmenuEntryClass
Specifies the only widget class that can be added to
the menu. For this to occur, the
DwtNmenuI sHomogeneous attribute must be
True. All other widget classes will not be added to
the menu.
DwtNmenuHistory Holds the widget ill of the last menu entry that was
activated. If DwtNmenuRadio is True,
DwtNmenuHistory holds the widget ID of the last
toggle button to change from off to on. This
attribute may be set to precondition option menus
and pop-up menus
DwtNentryCallbackIf this callback is defined, all menu entry activation
callbacks are revectored to call back through this
callback. If this callback is NULL, the individual
menu entry callbacks work as usual. For this
callback, the reason is DwtCRActi vate.
DwtNmenuHelpWidget
If non-NULL, the help menu widget points to the

menu item to be placed in the lower right comer of
the menu bar.
DwtNchangeVisAttsSpecifies a boolean value that, when True,
indicates that a menu widget can optionally make
these changes to its children: (1) Set the border to a
uniform widget; (2) align labels; (3) make margins
for the border highlight at least 2 pixels wide; (4) set
the indicator shape to oval for toggle buttons in radio
boxes; (5) set DwtNvisibleWhenOff to False
for toggle buttons.
When DwtNchangeVisAtts is False, a menu
widget cannot make any of these changes.
DwtNmenuExtendLastRow
Specifies the boolean value that indicates whether the
active area of each menu entry extends to the width
of the menu (for vertical menus) or the height of the
menu (for horizontal menus).
If True for vertical menus, all menu entries extend

to the menu width; if False, menu entries vary in

4-14 Menu Widget Functions

length depending on the length of the label in the
menu entry. If True for horizontal menus, all
menu entries extend to the menu height; if Fa 1 s e,
menu entries vary in height, depending on the length
of the label in the menu entry.
Table 4-4 lists the widget-specific attributes for the pull-down and pop-up
menu widgets. Descriptions of these attributes follow the table.

Table 4-4:

Pull-Down Menu and Pop-Up Menu Widgets

Attribute Name

Data Type

Default

DwtNmapCallback
DwtNunmapCallback

DwtCallbackptr
DwtCallbackptr

NULL
NULL

DwtNmapCallback Specifies the callback function or functions called
when the menu is mapped.
DwtNunmapCallbackSpecifies the callback function or functions called
when the menu is unmapped.

4.2 Creating Pull-Down Menu Entry Widgets
To create an instance of the pull-down menu entry widget, use
DwtPullDownMenuEntryor DwtPullDownMenuEntryCreate.
When calling DwtPullDownMenuEntry, you set the pull-down menu
entry widget attributes presented in the formal parameter list. For
DwtPullDownMenuEntryCreate, however, you specify a list of
attribute name/value pairs that represent all the possible pull-down menu
entry widget attributes. After you create an instance of this widget, you can
manipulate it using the appropriate X intrinsics functions. A description of
each follows:
Widget DwtPullDownMenuEntry (parent_widget, name,
x, y, label,
menu_id, callback, help_callback)
Widget parent_widget;
char * name ;
Position x, y;
DwtCompString label;
Widget menu_id;
DwtCallbackptr callback, help_callback;

Menu Widget Functions 4-15

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

label

Specifies the text of the label entry in the parent menu. This
argument sets the DwtNlabel attribute associated with
DwtLabelCreate.

menu id

Specifies the ID of the pull-down menu widget.

callback

Specifies the callback function or functions called back when
a button inside a pull-down menu entry widget is activated.
This argument sets the DwtNacti vateCallback and
DwtNpullingCallback attributes associated with
DwtPullDownMenuEntryCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget, attribute.
Widget DwtPullDownMenuEntryCreate

(parent_widget, name,
override_arglist,
override_argcount)

Widget parent_widget;
char * name ;
ArgList override_arglist;
int override_ argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _ arglist).
The DwtPullDownMenuEntry and
DwtPullDownMenuEntryCreate functions create an instance of the
pull-down menu entry widget and return its associated widget ID. A pulldown menu entry widget is made up of two parts: a label (within the parent

4-16 Menu Widget Functions

menu) and a select area or "hotspot." The hotspot is the full widget
window. Otherwise, the hotspot is a separate rectangle on the right side of
the entry label.
The following sections discuss these aspects of the pull-down menu entry
widget:

4.2.1

•

Callback information

•
•

Geometry management and resizing
Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActi vate

The user selected the pull-down menu
entry.

DwtCRHelpRequested

The user selected Help.

4.2.2

Geometry Management and Resizing
The pull-down menu entry widget may have a captive push button child, the
hotspot widget. This is the only child it allows. It refuses all other requests.
When the pull-down menu entry widget is resized by its parents, it calls
DwtLabelCreate's resize procedure and then repositions and resizes the
hotspot widget.

Menu Widget Functions 4-17

4.2.3

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the pull-down menu entry widget is:
•
•

core
composite

•

common

•
•

label
pulldown menu entry

Table 4-5 lists the attributes inherited by the pull-down menu entry widget.
For descriptions of the core and common attributes, see Chapter 1. For
descriptions of the label widget attributes, see Section 3.3.3.

Table 4-5: Attributes Inherited by the Pull-Down Menu Entry
Widget
Data Type

Default

DwtNx

Position

DwtNy

position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations

xtTranslations
int
XtTranslations

Determined by the geometry
manager
Determined by the geometry
manager
The DwtNlabel width, plus the
DwtNhot SpotP ixmap width or
the DwtNpixmap width, plus
DwtNmarginWidth times two
The DwtNlabelor
DwtNpixmap height, plus
DwtNmarginHeight times two
zero pixels
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL

Attribute Name

Core Attributes

4-18 Menu Widget Functions

Table 4-5:

(continued)

Attribute Name

Data Type

Default

DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

Boolean
Screen *
DwtCallbackPtr

True
The parent screen

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr

Default foreground color
Default foreground color

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font

NULL

Label Attributes

4.2.4

DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap
Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter

NULL
Zero
Zero
Zero
Zero
True, if the widget is created
with a width and height of zero
Fa 1 s e, if the widget is created
with a non-zero width and height

Widget-Specific Attributes
Table 4-6 lists the widget-specific attributes for the pull-down menu entry
widget. Descriptions of these attributes follow the table.

Menu Widget Functions 4-19

Table 4-6: Widget-Specific Attributes for the Pull-Down Menu
Entry Widget
Attribute Name

Data Type

Default

DwtNsubMenuId
DwtNactivateCallback
DwtNpullingCallback
DwtNhotSpotPixmap

Widget
DwtCallbackptr
DwtCallbackPtr
Pixmap

NULL
NULL
NULL
NULL

DwtNsubMenuld

Specifies the widget ID of the submenu that will be
displayed when the pull-down menu is activated.

DwtNactivateCallback
Specifies the callback that is executed when the user
releases a button inside the pull-down menu widget.
For this callback, the reason is DwtCRActi vate.
DwtNpullingCallback
Specifies the callback function or functions called
just prior to pulling down the submenu. This
callback occurs just before the submenu's map
callback. You can use this callback to defer the
creation of the submenu. For this callback, the
reason is DwtCRActi vate.
DwtNhot SpotP ixrnapSpecifies the pixmap to use for the hotspot icon.

4.3 Creating an Option Menu Widget
To create an instance of the option menu widget, use DwtOptionMenu or
DwtOptionMenuCreate. When calling DwtOptionMenu, you set the
option menu widget attributes presented in the formal parameter list. For
DwtOptionMenuCreate, however, you specify a list of attribute
name/value pairs that represent all the possible option menu widget attributes.
Mter you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions. A description of each follows:
Widget DwtOptionMenu (parent_widget, name, x, y,
label, sub_menu_id,
entry callback, help callback)
Widget parent_widget; char * name ;
Position x, y;
DwtCornpString label;

4-20 Menu Widget Functions

Widget sub_menu_id;
DwtCallbackPtr entry_callback, help_callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

label

Specifies the text in the menu label. This argument sets the
DwtNlabel attribute associated with DwtMenuCreate.

sub menu id

Specifies the widget ID of the pull-down menu associated
with the option menu during the creation phase.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtOptionMenuCreate (parent_widget, name,

override_arglist, override_argcount)
Widget parent_widget;
char * name ;
ArgList override_arglist;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

Menu Widget Functions 4-21

The DwtOptionMenu and DwtOptionMenuCreate functions create an
instance of the option menu widget and return its associated widget ID. The
option menu widget is a composite widget containing other subwidgets
(toggle button widgets). It displays and handles an application option list of
attributes or modes of the menu topic. Basically, the option menu consists of
a label identifying the menu and an active area to the right. This composite
widget contains other subwidgets (toggle button widgets) in the active area.
It displays the current option selected, and, on request, generates a pop-up
menu with specific options available. In addition, it ensures that a user can
select only one choice at any given time.
If DwtNentryCallback is non-NULL, then all the toggle button
callbacks will execute the entry_callback function, rather than the procedure
specified in the toggle. Otherwise, if DwtNentryCallback is NULL,
then the individual callbacks work as usual.

Option menus also position the pop-up part of the menu so that the menu
history widget covers the selection part of the option menu. Option menus
also copy the label of the menu history widget into the selection part.
The following sections discuss these aspects of the option menu widget:
•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

The option menu widget follows the same rules for geometry management
and resizing as its superclass the menu widget. For information on geometry
management and resizing, see Section 4.1.1.2.

4.3.1

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
Widget s_widget;
char *s_tag;
char *s_callbackstruct;
DwtMenuCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActi vate

The user selected a menu entry.

DwtCRHelpRequested

The user selected help.

4-22 Menu Widget Functions

The event member is a pointer to the Xlib structure XEvent, which
describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding. The s_widget member is set to the ID of the activating
sub widget. The s_tag member is set to the tag supplied by the application
programmer when the subwidget callback function was specified. The
s_callbackstruct member is set to the subwidget's callback structure.

4.3.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the option menu widget is:
•
•

core
composite

•

common

•
•

menu
option menu

Table 4-7 lists the attributes inherited by the option menu widget. For
descriptions of the core and common attributes, see Chapter 1. For
descriptions of the menu widget attributes, see Section 4.1.1.4.

Table 4-7: Attributes Inherited by the Option Menu Widget
Data Type

Default

DwtNx

Position

DwtNy

position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
Set as large as necessary to hold
all child widgets
Set as large as necessary to hold
all child widgets
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True

Attribute Name

Core Attributes

Menu Widget Functions 4-23

Table 4-7:

(continued)

Attribute Name

Data Type

Default

DwtNancestorSensitive

Boolean

The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

NULL

Depth of the parent window
NULL

True
The parent screen
NULL

Common Attributes

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList

DwtNhelpCallback

DwtCallbackPtr

NULL

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char
unsigned char

Zero pixels
3 pixels
Three pixels
DwtOrientationVertical
True
Zero pixels
True
DwtAlignmentBeginning
DwtMenuPackingTight(fur
all menu types except for radio
boxes)

Default foreground color
Default foreground color
NULL
NULL

DwtDirectionRightDown
The default XUI Toolkit font
Used only by gadget children

Menu Attributes

DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

DwtMenuPackingColumn~or

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

4-24 Menu Widget Functions

radio boxes)
One row or column
False
True (for radio boxes)
True
False

Table 4-7:

(continued)

Attribute Name

Data Type

Default

DwtNmenuEntryClass

WidgetClass

NULL

True (for radio boxes)

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

4.3.3

Widget
DwtCallbackptr
Widget
Boolean
Boolean

Radio boxes, however, default to
the togglebuttonwidgetc1ass.
Zero

NULL
NULL
True
True

Widget-Specific Attributes
Table 4-8 lists the widget-specific attributes for the option menu widget.
Descriptions of these attributes follow the table.

Table 4-8: Widget-Specific Attributes for the Option Menu
Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNsubMenuld

DwtCompString
Widget

Widget name
Zero

DwtNlabel

Specifies the label that will be placed to the left of
the current value.

DwtNsubMenuld

Specifies the widget ID of the pull-down menu
associated with the option menu during the creation
phase.

4.4 Menu Convenience Functions
To position the menu when the user presses MB2, use
DwtMenuPosi tion.

Menu Widget Functions 4-25

void DwtMenuPosition (position, event)
Widget position;
XEvent * event i

position

Specifies the position of the menu.

event

Specifies the event passed to the action procedure which
manages the pop-up menu.

The DwtMenuPosition function positions the menu when the user
presses MB2. This must be called before managing the pop-up menu.
To keep an entry highlight after the user clicks on a menu item, use
DwtPullDownMenuEntryHilite.
void DwtPullDownMenuEntryHilite (pulldown, highlight)
Widget pulldown;
int highlight;

position

Specifies the pulldown menu ..

highlight

Specifies whether a menu entry is highlighted. If the value is
one, the entry is highlighted. If the value is zero, the entry is
not highlighted.

The DwtPullDownMenuEntryHilite function keeps an entry highlight
after the user clicks on a menu item.

4.5 Creating a Separator Widget
To create an instance of the separator widget, use DwtSeparator or
DwtSeparatorCreate. When calling DwtSeparator, you set the
widget attributes presented in the formal parameter list. For
DwtSeparatorCreate, however, you specify a list of attribute
name/value pairs that represent all the possible separator widget attributes.
After you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions. A description of each follows:
Widget DwtSeparator (parent_widget, name, x, y, orientation)
Widget parent_widget i
char * name ;
Position x, Yi
unsigned char orientation;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the

4-26 Menu Widget Functions

parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

orientation

Specifies whether the separator is displayed vertically or
horizontally . You can pass
DwtOrientationHorizontalor
DwtOrientationVertical. This argument sets the
DwtNorientation attribute associated with
DwtSeparatorCreate.
A separator widget draws a centered single pixel line
between the appropriate margins. For example, a horizontal
separator draws a horizontal line from the left margin to the
right margin. It is placed vertically in the middle of the
widget.

Widget DwtSeparatorCreate (parent_widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char * name;
ArgList override_arglisti
int override_argcount;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Menu Widget Functions 4-27

The following sections discuss these aspects of the separator widget:

4.5.1

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the separator widget is:
•
•

core
composite

•

common

•
•

label
separator

Table 4-9 lists the attributes inherited by the separator widget. For
descriptions of the core and common attributes, see Chapter 1. For
descriptions of the label widget attributes, see Section 3.3.3.

Table 4-9: Attributes Inherited by the Separator Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
int
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
3 pixels
3 pixels
zero
Default foreground color

DwtNaccelerators

XtTranslations

Core Attributes

4-28 Menu Widget Functions

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL

Table 4-9:

(continued)

Attribute Name

Data Type

Default

DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

int
NOT SUPPORTED
Boolean
Screen *
DwtCallbackptr

Depth of the parent window
True
The parent screen
NULL

Common Attributes
Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
NOT SUPPORTED

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown

DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap
Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter
NULL
Zero
Zero
Zero
Zero
True, if the widget is created
with a width and height of zero
Fa 1 s e, if the widget is created
with a non-zero width and height

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Label Attributes

4.5.2 Widget-Specific attributes
Table 4-10 lists the widget-specific attribute for the separator widget. The
description of this attribute follows the table.

Menu Widget Functions 4-29

Table 4-10: Widget-Specific Attribute for the Separator Widget
Attribute Name

Data Type

Default

DwtNorientation

unsigned char

DwtOrientationHorizontal

DwtNorientation Specifies whether the separator is displayed vertically
or horizontally. You can pass
DwtOrientationHorizontalor
DwtOrientationVertical. A separator widget
draws a centered single pixel line between the
appropriate margins. For example, a horizontal
separator draws a horizontal line from the left margin
to the right margin. It is placed vertically in the
middle of the widget.

4-30 Menu Widget Functions

Dialog Box and Text Widget Functions

A dialog box is a window that solicits input from the user and displays
messages. The user responds to the input requests or messages by means of
controls within the dialog box. Your application creates dialog boxes, and
the window manager manages them. This chapter discusses functions you
can use to:

•
•
•
•
•
•
•
•
•

Create a dialog box widget
Create an attached dialog box widget
Create a simple text widget
Manipulate a simple text widget
Create a compound string text widget
Manipulate a compound string text widget
Create a color mix widget
Manipulate a color mix widget
Create a list box widget

The chapter concludes with a section that describes list box convenience
functions.

5.1

Creating a Dialog Box Widget
Dialog boxes are displayed in response to some user command to obtain
clarification or to notify the user. A dialog box may solicit the user for
additional information so it can execute a command. A dialog box may also
notify the user that a command was incorrectly entered, caution the user
about a potential problem, or notify the user of some unusual event.
To allow the user to enter input and to perform other application-related
tasks, your dialog boxes will probably make use of the controls found in
control panels. In addition, your dialog boxes may make use of other
controls:
•

Push buttons

•

Text entry fields

•

Option menus

•

List boxes

Dialog boxes are either modal or modeless. A modal dialog box stops the
work session and solicits input from the user. A modeless dialog box also
solicits input from the user but does not stop the user's work or the activity
of any application, including the application that displayed the dialog box.
For more information on modal and modeless dialog boxes, and for
discussions on displaying dialog boxes, working with dialog box controls and
labels, and designirig dialog boxes, see the XU! Style Guide.
The following are ways to create instances of the dialog box widget:
•

For modal, modeless, and work area dialog box widgets call
DwtDialogBox and pass the appropriate constant to the style

argument.
•

For modal and modeless dialog box widgets call
DwtDialogBoxPopupCreate and pass the appropriate constant to
DwtNstyle.

•

For work area dialog box widgets call DwtDialogBoxCreate and
pass the appropriate constant to DwtNstyle.

When calling DwtDialogBox, you set the dialog box widget attributes
presented in the formal parameter list. For DwtDialogBoxCreate and
DwtDialogBoxPopupCreate, however, you specify a list of attribute
name/value pairs that represent all the possible dialog box widget attributes.
After you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions. A description of each follows:
Widget DwtDialogBox (parent_widget, name, defaultyosition,
x, y, title, style,
map_callback, help_callback)
Widget parent_widget;
char * name ;
Boolean defaultyosition;
Position x, y;
DwtCompString title;
unsigned char style;
DwtCallbackptr map_callback, help_callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

defaultyositionSpecifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the

5-2 Dialog Box and Text Widget Functions

parent window. If False, the specified DwtNx and
DwtNy attributes are used to position the widget.
If the dialog box is displayed partially off the screen as a
result of being centered in the parent window, the centering
rule is violated. When this occurs, the parent window is
repositioned so that the entire dialog box is displayed on the
screen.

The pop-up dialog box is recentered every time it is popped
up. Consequently, if the parent moves in between
invocations of the dialog box, the box pops up centered in
the parent window's new location. However, the dialog box
does not dynamically follow its parent while it is displayed.
If the parent is moved, the dialog box will not move until the
next time it is popped up.
If the user moves the dialog box with the window manager,
the toolkit turns off DwtNdefaul tPosi tion. This
results in the dialog box popping up in the location specified
by the user on each subsequent invocation. This argument
sets the DwtNdefaul tPosi tion attribute associated
with DwtDialogBoxCreate.
x

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

title

Specifies the compound-string label. The label is given to
the window manager for the title bar if DwtNstyle is
DwtModeless. This argument sets the DwtNti tIe
attribute associated with DwtDialogBoxPopupCreate.

style

Specifies the style of the dialog box widget. You can pass
DwtModal, DwtModeless, or DwtWorkarea. You
cannot change DwtNstyle after the widget is created.
This argument sets the DwtNstyle attribute associated
with DwtDialogBoxCreate or
DwtDialogBoxPopupCreate.

map_callback Specifies the callback function or functions called when the
window is about to be mapped. For this callback, the reason
is DwtCRMap. Note that map callback is supported only if
style is DwtModal or DwtM~deless. If style is

Dialog Box and Text Widget Functions 5-3

DwtWorkarea, map_callback is ignored.

This argument sets the DwtNmapCallback attribute
associated with DwtDialogBoxPopupCreate.
help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtDialogBoxCreate (parent_widget, name,
override_argUst, override_argcount)
Widget parent_widget;
char * name ;
ArgLi st override_ argUst ;
int override_argcount;
Widget DwtDialogBoxPopupCreate (parent_widget, name,
override_arglist ,
override_argcount )
Widget parent_widget;
char * name ;
ArgList override_argUst;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _argUst).

Depending on the constant you pass to DwtNstyle, the DwtDialogBox
function creates a dialog box or a pop-up dialog box widget. The
DwtDialogBoxCreate function creates a dialog box widget, and
DwtDialogBoxPopupCreate creates a pop-up dialog box widget. Upon
completion, these functions return the associated widget ID.
The dialog box widget is a composite widget that contains other subwidgets.
Each subwidget displays information or requests and/or handles input from
the user.
The dialog box widget functions as a container only, and provides no input
semantics over and above the expressions of the widgets it contains.
Subwidgets can be positioned within the dialog box in two ways: by font
units and by pixel units. By default, subwidgets are positioned in terms of
font units (that is, DwtNunits is DwtFontUnits). The X font units are
defined to be one-fourth the width of whatever font is supplied for the

5-4 Dialog Box and Text Widget Functions

common attribute DwtNfont. The Y font units are defined to be oneeighth the width of whatever font is supplied for DwtNfont. (Width is
taken from the QUAD_WIDTH property of the font.) Subwidgets can also
be positioned in terms of pixel units (that is, DwtNuni t s is
DwtPixelUnits).

Note that when changing DwtNtextMergeTranslations, the existing
widgets are not affected. The new value for
DwtNtextMergeTranslations acts only on widgets that are added
after the pop-up dialog box is created.
Pop-up dialog box widgets create their own shells as parents. Therefore, to
set the colormap of a pop-up dialog box, you must set the colormap of its
parent shell. (To find the parent shell, use XtParent.) For nonpop-up
widgets, the shell widget ID is returned from Xtlnitialize. You need
only set the colormap once on the returned shell widget.
The following sections discuss these aspects of the dialog box and pop-up
dialog box widgets:

5.1.1

•

Callback information

•

Geometry management

•
•

Resizing
Widget class hierarchy and inherited attributes

•

Widget-specific attributes

•

Constraint attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For the callbacks associated with
DwtDialogBoxCreate, the reason member can be set to:
DwtCRFocus

The dialog box has received the input
focus.

DwtCRHelpRequested

The user has selected Help.

Dialog Box and Text Widget Functions 5-5

For the callbacks associated with DwtDialogBoxPopupCreate, the
reason member can be set to:
DwtCRMap

The dialog box is about to be mapped.

DwtCRUnmap

The dialog box is about to be unmapped.

DwtCRFocus

The dialog box has received the input
focus.

DwtCRHelpRequested

The user has selected Help.

5.1.2

Geometry Management
The dialog box (or pop-up dialog box) widget is a generic container that
treats all its children equally in terms of geometry management. When a
child is first added to a dialog box, it is placed using the DwtNx, DwtNy,
DwtNwidth, DwtNheight, and DwtNborderWidth core attributes
specified in the widget. The dialog box does not override any of the
geometry of its children.
The value of the DwtNchildOverlap attribute affects how the geometry
manager reacts to geometry requests from its children. If True (the
default), the dialog box approves a request from a child, even if the request
results in the child overlapping another child of the dialog box. If False,
the dialog box geometry manager denies such requests.

5.1.3

Resizing
The resizing behavior of the dialog box (or pop-up dialog box) widget is
controlled by the DwtNresize attribute. See the description of that
attribute.

5.1.4

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the dialog box and pop-up dialog box widgets
is:
•

core

5-6 Dialog Box and Text Widget Functions

•

composite

•

constraint

•

dialog

Based on this class hierarchy, the dialog box and pop-up dialog box widgets
inherit attributes from the core, composite, and constraint widgets. Note that
you cannot set the attributes for the constraint widget; therefore, they are not
shown. The inherited attributes are listed in the following tables.
Table 5-1 lists the attributes inherited by the dialog box and pop-up dialog
box widget. For descriptions of the core attributes, see Chapter 1.
Table 5-1: Attributes Inherited by the Dialog Box and Pop-Up
Dialog Box Widgets
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Dialog Box and Text Widget Functions 5-7

5.1.5

Widget-Specific Attributes
Table 5-2 lists the widget-specific attributes for the dialog box and pop-up
dialog box widgets. Table 5-3 lists additional widget-specific attributes
supported only by the pop-up dialog box widget. Descriptions of these
attributes follow the tables.

Table 5-2: Widget-Specific Attributes for the Dialog Box and
Pop-Up Dialog Box Widgets
Attribute Name

Data Type

Default

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNstyle

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackptr
unsigned char
unsigned char
unsigned char

DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth

DwtCallbackPtr
XtTranslations
Dimension

DwtNmarginHeight

Dimension

DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNgrabKeySyms

Boolean
Boolean
unsigned char
KeySym

DwtNgrabMergeTranslations

XtTranslations

Default foreground color
Default foreground color
NULL
NULL
The default XUI Toolkit font
NULL
DwtDirectionRightDown
DwtFontUnits
For DwtDialogBoxCreate,
the default is DwtWorkarea.
For
DwtDialogBoxPopupCreate
the default is DwtModeless.
NULL
NULL
For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreate
the default is 3 pixels.
For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreate
the default is 3 pixels.
False
True
DwtResizeGrowOnly
The default array contains the Tal
key symbol.
The default syntax is:
"-Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSNEXT()\n'
Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSPREVO";

5-8 Dialog Box and Text Widget Functions

Table 5-3: Widget-Specific Attributes for the Pop-Up Dialog Box
Widget
Attribute Name

Data Type

Default

DwtNtitle

DwtCompString

DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

DwtCallbackptr
DwtCallbackPtr
Boolean

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton
DwtNautoUnrealize

Boolean
Widget
Widget
Boolean

When DwtNstyle is
DwtModal, the default is NULL
When DwtNstyle is
DwtModeless, the default is the
widget name
NULL
NULL
True for modal dialog box
Fa 1 s e for modeless dialog box
True (that is, no window
manager resize button)
True
NULL
NULL
False

DwtNforeground

Specifies the color of foreground gadget children in
the widget window.

DwtNhighlight

Specifies the color used for highlighting gadget
children.

DwtNhighlightPixmap
Specifies the pattern and color used for highlighting
gadget children.
DwtNuserData

Specifies any user private data to be associated with
the widget. The XUI Toolkit does not interpret this
data.

Dialog Box and Text Widget Functions 5-9

to right and wraps Up);
DwtDirectionLeftDown (text is drawn from
right to left and wraps down); or
DwtDirectionLeftUp (text is drawn from right
to left and wraps up).
DwtNfont

Specifies the font of the text used in gadget children.

DwtNhelpCallback Specifies the callback function or functions called
when a help request is made.
DwtNuni t s

Specifies the type of units for the DwtNx and
DwtNy attributes. You use these when adding child
widgets to the dialog box. The DwtNuni t s
attribute cannot be changed after the widget is
created. You can pass DwtPixelUnits or
DwtFontUni ts.

DwtNstyle

Specifies the style of the dialog box widget. For
DwtDialogBoxPopupCreate you can pass
DwtModal or DwtModeless. For
DwtDialogBoxCreate you can pass
DwtWorkarea. You cannot change DwtNstyle
after the widget is created.

DwtNfocusCallbackSpecifies the callback function or functions called
when the dialog box accepted the input focus. For
this callback, the reason is DwtCRFocus.
DwtNtextMergeTranslations
Specifies the translation manager syntax that will be
merged with each text widget.
DwtNmarginWidth Specifies the number of pixels between the maximum
right border of a child widget window and the dialog
box.
DwtNmarginHeight Specifies the number of pixels between the maximum
bottom border of a child widget window and the
dialog box.
DwtNdefaultPosition
Specifies a boolean value that, when True, causes
DwtNx and DwtNy to be ignored and forces the
default widget position. The default widget position
is centered in the parent window. If Fa 1 s e, the
specified DwtNx and DwtNy attributes are used to
position the widget.
If the dialog box is displayed partially off the screen
as a result of being centered in the parent window,

5-10 Dialog Box and Text Widget Functions

the centering rule is violated. When this occurs, the
parent window is repositioned so that the entire
dialog box is displayed on the screen.
The pop-up dialog box is recentered every time it is
popped up. Consequently, if the parent moves in
between invocations of the dialog box, the box pops
up centered in the parent window's new location.
However, the dialog box does not dynamically
follow its parent while it is displayed. If the parent
is moved, the dialog box will not move until the next
time it is popped up.
If the user moves the dialog box with the window

manager, the toolkit turns off
DwtNdefaul tPosi tion. This results in the
dialog box popping up in the location specified by
the user on each subsequent invocation.
DwtNchildOverlap Specifies a boolean value that, when True,
indicates that the dialog box approves geometry
requests from its children that result in one child
overlapping other children. If Fa 1 s e, the dialog
box disapproves these geometry requests.
DwtNresize

Specifies how the dialog box resizes when its
children are managed and unmanaged and when
geometry requests occur. You can pass
DwtResizeFixe~ DwtResizeGrowOnly,or
DwtResizeShrinkWrap.
DwtResizeFixed indicates that the dialog box
does not change its size when children are added or
deleted, or on geometry requests from its children.
DwtResizeGrowOnly indicates that the dialog
box always attempts to grow as necessary when
children are added or deleted, or on geometry
requests from its children.
DwtResizeShrinkWrap indicates that the dialog
box always attempts to grow or shrink to fit its
current set of managed children as children are added
or deleted, or on geometry requests from its children.

DwtNgrabKeySyms Specifies a NULL-terminated array of keysyms. The
dialog box calls the Xlib function XGrabKey for
each keysym. XGrabKey specifies
AnyModifier for modifiers, GrabModeAsync
for pointer_mode, and GrabModeSync for

Dialog Box and Text Widget Functions 5-11

keyboard_mode. The dialog box uses the
XGrabKey function in conjunction with the value of
DwtNgrabMergeTranslations to implement
moving the focus among its children in a
synchronous manner. You cannot change this
attribute after the widget is created.

DwtNgrabMergeTranslations
Specifies the parsed translation syntax to merge into
the dialog box syntax to handle the key events. The
syntax is merged when the dialog box is first
realized. Any change made to this attribute after the
dialog box is realized will not have any effect.
DwtNt it 1 e

Specifies the compound-string label. The label is
given to the window manager for the title bar if
DwtNstyle is DwtModeless.

DwtNmapCallback Specifies the callback function or functions called
when the window is about to be mapped. For this
callback, the reason is DwtCRMap.
DwtNunmapCallbackSpecifies the callback function or functions called
when the window was unmapped. For this callback,
the reason is DwtCRUnmap.
DwtNtakeFocus

Specifies a boolean value that, when True,
indicates that the dialog box takes the input focus
when managed.

DwtNnoResize

Specifies a boolean value that, when True,
indicates that a modal or modeless dialog box does
not have a window manager resize button. When
False, the dialog box has a window manager resize
button.

DwtNautoUnmanage Specifies a boolean value that, when True,
indicates that the dialog box unmanages itself when
any push button is activated. This attribute cannot be
changed after widget creation.
DwtNdefaultButtonSpecifies the ID of the push button widget that is
activated when the user presses the RETURN or
ENTER key.
DwtNcancelButton Specifies the ID of the push button widget that is
activated when the user presses the Shift and Return
keys simultaneously.
DwtNautoUnrealizeSpecifies a boolean value that, when False,
indicates that the dialog box creates the window(s)

5-12 Dialog Box and Text Widget Functions

for itself and its children when it is first managed,
and never destroys them. If True, the dialog box
re-creates the window(s) every time it is managed,
and destroys them when it is unmanaged.
The setting of this attribute is a performance tradeoff
between the client cpu load (highest when set to
True), and the server window load (highest when
set to False).

5.1.6

Constraint Attributes
The following constraint attributes are passed on to any widget that is made a
child of a dialog box widget. These constraint values are used only for
dialog boxes that have the DwtNunits attribute set to DwtFontUnits.
DwtNfontX

Specifies the placement of the left hand side of the
widget window in font units. The default is the
value of DwtNx.

DwtNfontY

Specifies the placement of the top of the widget
window in font units. The default is the value of
DwtNy.

5.2 Creating an Attached Dialog Box Widget
The following are ways to create instances of the attached dialog box widget:
•

For modal, modeless, and work area attached dialog box widgets call
DwtAttachedDB and pass the appropriate constant to the style
argument.

•

For modal and modeless attached dialog box widgets call
DwtAttachedDBPopupCreate.

•

For work area attached dialog box widget call
DwtAttachedDBCreate.

When calling DwtAttachedDB, you set the attached dialog box widget
attributes presented in its formal parameter list. For
DwtAttachedDBCreateand DwtAttachedDBPopupCreate,
however, you specify a list of attribute name/value pairs that represent all the
possible attached dialog box widget attributes. After you create an instance
of this widget, you can manipulate it using the appropriate X intrinsics
functions. A description of each follows:

Dialog Box and Text Widget Functions 5-13

Widget DwtAttachedDB (parent_widget, name, dejaultyosition,
x, y, title, style,
map_cal/back, help_callback)
Widget parent_widget;
char * name ;
Boolean dejaultyosition;
Position x, y;
DwtCompString title;
unsigned char style;
DwtCallbackPtr map_cal/back, help_callback;

parent_widget Specifies the parent widget ID.
name
Specifies the name of the created widget.
dejaultyositionSpecifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. If False, the specified DwtNx and
DwtNy attributes are used to position the widget. This
argument sets the DwtNdefaul tPosi tion attribute
associated with DwtDialogBoxCreate.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

title

Specifies the compound-string label. The label is given to
the window manager for the title bar if the DwtNstyle
attribute associated with DwtDialogBoxPopupCreate
is DwtModalor DwtModeless. However, the label is
used in the border if the DwtNstyle attribute associated
with DwtDialogBoxCreate is DwtWorkarea.

style

The attribute name associated with this argument is
DwtNtitle.
Specifies the style of the dialog box widget. You can pass
DwtModal, DwtModeless, or DwtWorkarea. This
argument sets the DwtNstyle attribute associated with
DwtDialogBoxCreate.

map_cal/back Specifies the callback function or functions called when the
window is about to be mapped. For this callback, the reason

5-14 Dialog Box and Text Widget Functions

is DwtCRMap. This argument is ignored if DwtNstyle is
DwtWorkarea.

This argument sets the DwtNmapCallback attribute
associated with DwtDialogBoxPopupCreate.
help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtAttachedDBCreate (parent_widget, name,
override_argUst, override_ argcount)
Widget parent_widget;
char *name;
ArgList override_argUst;
int override_argcount ;
Widget DwtAttachedDBPopupCreate (parent_widget, name,
override_argUst ,
override_argcount)
Widget parent_widget;
char * name ;
ArgList override_argUst;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_ argUstSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _ argUst).

The DwtAttachedDB and DwtAttachedDBCreate functions create an
instance of an attached dialog box widget or an attached dialog box pop-up
widget and return its associated widget ID. The
DwtAttachedDBPopupCreate function creates an instance of a pop-up
attached dialog box widget and returns its associated widget ID.
The attached dialog box acts as a container only, and provides no input
semantics over and above the semantics of the widgets that it contains. It
differs from the dialog box in its handling of child widgets. Constraints are
placed on each child widget at the time of creation. The default values for
the constraint attributes are placed on the child unless you specify values for
the constraint attributes. You specify these values either in the
override_argUst or by calling XtSetValues.

Dialog Box and Text Widget Functions 5-15

By using the constraint attributes, you can attach each of the four sides of a
child widget (top, bottom, right side, and left side) to a side of the parent
attached dialog box, a side of another child widget, to a relative position
within the attached dialog box, to itself, or to nothing. The possible
attachments for each of the four sides are described in the Constraint
Attributes section. Specifying these attachments allows you to maintain the
position of child widgets within the attached dialog box as resizing occurs.
If only one attachment in a direction is specified with no width or height, the
default width or height for the widget is used.
For all attachment types, you can optionally specify an offset in pixels or font
units. The offset determines the amount of space between the side of the
child widget and the side or position you attach it to. By default, the child
widgets are positioned in an attached dialog box in terms of font units rather
than pixel units. (That is, DwtNunits is DwtFontUnits.) The X font
units are defined to be one-fourth the width of whatever font is supplied for
the common attribute DwtNfont. The Y font units are defined to be oneeighth the width of whatever font is supplied for DwtNfont.
The offsets given are automatically negated when dealing with right and
bottom sides. For example, a displacement of 5 means that the side stays 5
units to the right of its attachment if a left side, and 5 units to the left if a
right side.
Displacements default to a value specified in the attached dialog box for
attachments to the attached dialog box and the widget, and half the value
specified if attached to a position. Attaching to a point allows several
widgets to grow proportionally; the space between them should be the default
displacement. There are separate horizontal and vertical defaults.
You can determine whether the attached dialog box will honor resize
geometry requests from a given child widget by appropriately setting the
DwtNresize attribute for that child. If it does honor a request, the attached
dialog box reconfigures all child widgets based on the initial coordinate
information.
You can add child widgets after the attached dialog box widget has been
realized. If there is extra room in the attached dialog box, the new child
widget will appear. If there is not enough room, the attached dialog box will
ask the geometry manager for permission to resize.

5-16 Dialog Box and Text Widget Functions

The following sections discuss these aspects of the attached dialog box
widget:
•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

•

Constraint attributes

The attached dialog box widget and attached dialog box pop-up widget
follow the same rules for geometry management and resizing as their
superclass, the dialog box widget. For information on dialog box widget
geometry management and resizing, see Section 5.1.2.

5.2.1

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRMap

The attached dialog box is about to be
mapped.

DwtCRHelpRequested

The user selected Help.

5.2.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the attached dialog box widget is:
•
•
•

core
composite
constraint

Dialog Box and Text Widget Functions 5-17

•
•

dialog
attached dialog

The widget class hierarchy for the attached dialog box pop-up widget is:

•
•
•
•
•

core
composite
constraint
dialog
attached dialog box popup

Table 5-4 lists the attributes inherited by the attached dialog box and attached
dialog box pop-up widgets. For descriptions of the core and common
attributes, see Chapter 1. For descriptions of the dialog widget attributes, see
Section 5.1.5.

Table 5-4: Attributes Inherited by the Attached Dialog Box and
Attached Dialog Box Pop-Up Widgets
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Widget-specific
Widget-specific
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged

xtTranslations
int
XtTranslations
Boolean

Core Attributes

5-18 Dialog Box and Text Widget Functions

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the pan
widget's DwtNsensitivE
DwtNancestorSensiti,
attributes

NULL
Depth of the parent window

NULL
True

Table 5-4:

(continued)

Attribute Name

Data Type

Default

DwtNscreen
DwtNdestroyCallback

Screen *
DwtCallbackPtr

The parent screen

DwtNadbTopAttachment

DwtAttachmentType

DwtNadbBottomAttachment

DwtAttachmentType

DwtNadbLeftAttachment

DwtAttachmentType

DwtNadbRightAttachment

DwtAttachmentType

DwtAttachAdb if
DwtNrubberPositioningis
False
DwtAttachSelf if
DwtNrubberPositioningis
True
The default is DwtAttachNone
if DwtNrubberPositioning
is False.
The default is DwtAttachSelf
if DwtNrubberPosi tioning
is True.
The default is DwtAttachAdb
if DwtNrubberPositioning
is False.
The default is DwtAttachSelf
if DwtNrubberPositioning
is True.
The default is DwtAttachNone
if DwtNrubberPositioning
is False.
The default is DwtAttachSelf
if DwtNrubberPositioning
is True.

DwtNadbTopWidget
DwtNadbBottomWidget
DwtNadbLeftWidget
DwtNadbRightWidget
DwtNadbTopPosition
DwtNadbBottomPosition
DwtNadbLeftPosition
DwtNadbRightPosition
DwtNadbTopOffset

Widget
Widget
Widget
Widget
int
int
int
int
int

NULL

Constraint Attributes

NULL
NULL
NULL
NULL
Zero
Zero
Zero
Zero
The value specified with
DwtNdefaultVerticalOffset.
However, if
DwtNadbTopAttachmentis
DwtAttachPosi tion or
DwtAttachSelf, the default is
one-half the value specified with
DwtNdefaultVerticalOffset.

Dialog Box and Text Widget Functions 5-19

Table 5-4:

(continued)

Attribute Name

Data Type

Default

DwtNadbBottomOffset

int

DwtNadbLeftOffset

int

DwtNadbRightOffset

int

DwtNresizable

Boolean

The default is the value specified
with
DwtNdefaultVerticalOffset.
However, if
DwtNadbBottomAttachment
is DwtAttachPosition or
DwtAttachSelf, the default is
one-half the value specified with
DwtNdefaultVerticalOffset.
The default is the value specified
with
DwtNdefaultHorizontalOffsE
However, if
DwtNadbLeftAttachmentis
DwtAttachPosition or
DwtAttachSelf, the default is
one-half the value of
DwtNdefaultHorizontalOffsE
The value specified with
DwtNdefaultHorizontalOffsE
However, if
DwtNadbRightAttachment
~ DwtAttachPositionm
DwtAttachSelf, the default is
one-half the value specified with
DwtNdefaultHorizontalOffsE
True

Dialog Attributes

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNstyle

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char
unsigned char

Default foreground color
Default foreground color

DwtNfocusCallback
DwtNtextMergeTranslations

DwtCallbackPtr
XtTranslations

NULL
NULL

5-20 Dialog Box and Text Widget Functions

NULL
NULL
The default XUI Toolkit font

NULL
DwtDirectionRightDown
DwtFontUnits
For DwtDialogBoxCreate,
the default is DwtWorkarea.
For
DwtDialogBoxPopupCreate,
the default is DwtModeless.

Table 5-4:

5.2.3

(continued)

Attribute Name

Data Type

Default

DwtNmarginWidth

Dimension

DwtNmarginHeight

Dimension

DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNgrabKeySyms

Boolean
Boolean
unsigned char
KeySym

DwtNgrabMergeTranslations

XtTranslations

For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreate,
the default is 3 pixels.
For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreate,
the default is 3 pixels.
False
True
DwtResizeGrowOnly
The default array contains the Tab
key symbol.
The default syntax is:
"-Shift<KeyPress>Oxff09 :
DWTDIMOVEFOCUSNEXTO\n\
Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSPREVO";

Widget-Specific Attributes
Table 5-5 lists the widget-specific attributes for the attached dialog box and
attached dialog box pop-up widgets. Descriptions of these attributes follow
the table.

Table 5-5: Widget-Specific Attributes for the Attached Dialog
Box and Attached Dialog Box Pop-Up Widgets
Attribute Name

Data Type

Default

DwtNdefaultHorizontalOffset
DwtNdefaultVerticalOffset
DwtNrubberPositioning
DwtNfractionBase

int
int
Boolean
int

Zero
Zero
False
100

DwtNdefaultHorizontalOffset
Specifies the default horizontal offset for right and
left attachments. The offset determines the amount
Dialog Box and Text Widget Functions 5-21

of space between the left or right side of a child
widget and the side or position to which it is
attached.
DwtNdefaultVerticalOffset
Specifies the default vertical offset for the top and
bottom attachments. The offset determines the
amount of space between the top or bottom side of a
child widget and the side or position to which it is
attached.
DwtNrubberPositioning
Specifies a boolean value that, when False,
indicates that the child widget left and top sides
default to being attached to the left and top of the
attached dialog box. If True, the child widget sides
default to being attached to the left and top of the
attached dialog box.
DwtNfractionBase Specifies the denominator used in specifying
fractional positioning.

5.2.4 Constraint Attributes
The following constraint attributes belong to any widget that is made a child
of an attached dialog box widget. You cannot set these attributes on the
attached dialog box itself; you must set them on the child widget. Several of
these constraint attributes take an enumerated data type. You should not
change attachment attributes in an attached dialog box with XtSetValues,
as this could result in an infinite loop.
typedef enum _DwtAttachmentType {
DwtAttachNone,
DwtAttachAdb,
DwtAttachWidget,
DwtAttachPosition,
DwtAttachSelf,
DwtAttachOppWidget,
DwtAttachOppAdb,
DwtAttachmentType;

DwtNadbTopAttachment
Specifies how the top side of the child widget is
attached to its parent attached dialog box widget,
another child widget, a position, or itself.

The following describes the enumerated data type
values as they apply to this attribute:

5-22 Dialog Box and Text Widget Functions

Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
may be overridden by the defaults of other
attachments that affect this side.

DwtAttachAdb

Attach the top side of the child widget to the top
side of its parent attached dialog box.

DwtAttachOppAdb

Attach the top side of the child widget to the
bottom side of its parent attached dialog box.

DwtAttachWidget

Attach the top side of the child widget to the
bottom side of another child widget within the
parent attached dialog box.

DwtAttachOppWidget

Attach the top side of the child widget to the top
side of another child widget.

DwtAttachPosition

Attach the top side of the child widget to a
relative position inside the parent attached dialog
box. Specify the relative position as a fraction
of the total width or height of the attached
dialog box.

DwtAttachSelf

Attach the top side of the child widget to a
relative position corresponding to the side's
initial position in the attached dialog box.

DwtNadbBottomAttachment
Specifies how the bottom side of the widget is'
attached to the side of its parent attached dialog box
widget, another child widget, a position, or itself.

The following describes the enumerated data type
values as they apply to this attribute:
Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
overrides any default attachment that might
affect the side.

DwtAttachAdb

Attach this side to the bottom side of its parent
attached dialog box.

Dialog Box and Text Widget Functions 5-23

DwtAttachOppAdb

Attach this side to the top side of the parent
attached dialog box.

DwtAttachWidget

Attach this side to the top side of another child
widget within the parent attached dialog box.

DwtAttachOppWidget

Attach this side to the bottom side of another
child widget.

DwtAttachPosition

Attach this side to a relative position inside the
parent attached dialog box. Specify the relative
position as a fraction of the total width or height
of the attached dialog box.

DwtAttachSelf

Attach this to a relative position corresponding
to the side's initial position inside the parent
attached dialog box.

DwtNadbLeftAttachment
Specifies how the left side of the widget is attached
to the side of its parent attached dialog box widget,
another child widget, a position, or itself.

The following describes the enumerated data type
values as they apply to this attribute:
Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
overrides any default attachment that might
affect the side.

DwtAttachAdb

Attach this side to the left side of its parent
attached dialog box.

DwtAttachOppAdb

Attach this side to the right side of the parent
attached dialog box.

DwtAttachWidget

Attach this side to the right side of another child
widget within the parent attached dialog box.

DwtAttachOppWidget

Attach this side to the left side of another child
widget.

5-24 Dialog Box and Text Widget Functions

DwtAttachPosition

Attach this side to a relative position inside the
parent attached dialog box. Specify the relative
position as a fraction of the total width or height
of the attached dialog box.

DwtAttachSelf

Attach this side to a relative position
corresponding to the side's initial position in the
parent attached dialog box.

DwtNadbRightAttachment

Specifies how the right side of the widget is attached
to the side of its parent attached dialog box, another
child widget, a position, or itself.
The following describes the enumerated data type
values as they apply to this attribute:
Value

Meaning

DwtAttachNone

Do not attach this side. This type of attachment
overrides any default attachment that might
affect the side.

DwtAttachAdb

Attach this side to the right side of its parent
attached dialog box.

DwtAttachOppAdb

Attach this side to the left side of the parent
attached dialog box.

DwtAttachWidget

Attach this side to the left side of another child
widget within the parent attached dialog box.

DwtAttachOppWidget

Attach this side to the right side of another child
widget.

DwtAttachPosition

Attach this side to a relative position inside the
parent attached dialog box. Specify the relative
position as a fraction of the total width or height
of the attached dialog box.

DwtAttachSelf

Attach this side to a relative position
corresponding to the side's initial position in the
parent attached dialog box.

DwtNadbTopWidget Specifies the child widget that the top side is
attached to if DwtNadbTopAttachment is

Dialog Box and Text Widget Functions 5-25

DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNadbBottomWidget
Specifies the widget that the bottom side is attached
to if DwtNadbBottornAttachment is
DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNadbLeftWidgetSpecifies the widget that the left side is attached to
if DwtNadbLeftAttachment is
DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNadbRightWidget
Specifies the widget that the right side is attached to
if DwtNadbRightAttachment is
DwtAttachWidget or DwtAttachOppWidget.
Otherwise, this attribute is ignored.
DwtNtopPosi tion Specifies the numerator used with
DwtNfractionBase to determine the relative
positioning of the top side if
DwtNadbTopAttachmentis
DwtAttachPosi tion. Otherwise, this attribute is
ignored.
DwtNadbBottomPosition
Specifies the numerator used with
DwtNfractionBase to determine the relative
positioning of the bottom side if
DwtNadbBottornAttachmentis
DwtAttachPosi tion. Otherwise, this attribute is
ignored.
DwtNadbLeftPosition
Specifies the numerator used with
DwtNfractionBase to determine the relative
positioning of the left side if
DwtNadbLeftAttachmentis
DwtAttachPosition. Otherwise, this attribute is
ignored.
DwtNadbRightPosition
Specifies the numerator used with the
DwtNfractionBase to determine the relative
positioning of the right side if
DwtNadbRightAttachmentis
DwtAttachPosi tion. Otherwise, this attribute is
ignored.
5-26 Dialog Box and Text Widget Functions

DwtNadbTopOffset Specifies the offset of the top side from the position,
widget, or attached dialog box.
DwtNadbBottomOffset
Specifies the offset of the bottom side from the
position, widget, or attached dialog box.
DwtNadbLeftOffsetSpecifies the offset of the left side from the position,
widget, or attached dialog box.
DwtNadbRightOffset
Specifies the offset of the right side from the
position, widget, or attached dialog box.
DwtNresizable

Specifies a boolean value that, when True,
indicates that the attached dialog box can change the
size of the child widget. If False, indicates that
the attached dialog box cannot change the size of the
child widget.

5.3 Creating a Simple Text Widget
To create an instance of the simple text widget, use DwtSText or
DwtSTextCreate. When calling DwtSText, you set the text widget
attributes presented in the formal parameter list. For DwtSTextCreate,
however, you specify a list of attribute name/value pairs that represent all the
possible simple text widget attributes. After you create an instance of this
widget, you can manipulate it using the appropriate X intrinsics functions. A
description of each follows:
Widget DwtSText (parent_widget, name, x, y, eols, rows, value)
Widget parent_widget;
char *name;
Position x, y;
Dimension eols, rows;
char
* value;
parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.
Dialog Box and Text Widget Functions 5-27

cols

Specifies the width of the text window measured in character
spaces. This argument sets the DwtNcols attribute
associated with DwtSTextCreate.

rows

Specifies the height of the text window measured in character
heights or number of line spaces. This argument sets the
DwtNrows attribute associated with DwtSTextCreate.

value

Specifies the actual text to display. This argument sets the
DwtNvalue attribute associated with DwtSTextCreate.

Widget DwtSTextCreate (parent_widget, name,
override argUst, override argcount)
Widget parent widget;
char * name ;
ArgList override_argUst;
in t override_ argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_argUstSpecifies the application override argument list.
override_ argcount
Specifies the number of attributes in the application override
argument list (override _argUst).

The DwtSText and DwtSTextCreate functions create an instance of a
simple text widget and return its associated widget ID. The text widget
enables the application to display a single or multiline field of text for input
and edit manipulation by the user. By default, the text window grows or
shrinks as the user enters or deletes text characters. Note that the text
window does not shrink below the initial size set at creation time.
The following sections discuss these aspects of the simple text widget:
•
•

Callback information
Widget class hierarchy and inherited attributes

•

Widget-specific attributes

The simple text widget does not support children; therefore, there is no
geometry or resize semantics.

5.3.1

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

5-28 Dialog Box and Text Widget Functions

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRFocus

The simple text widget has received the
input focus.

DwtCRLostFocus

The simple text widget has lost the input
focus.

DwtCRVal ueChanged

The user changed the value of the text
string in the simple text widget.

DwtCRHelpRequested

The user selected Help.

5.3.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the simple text widget is:
•

core

•
•

text
stext

Table 5-6 lists the attributes inherited by the simple text widget. For
descriptions of the core attributes, see Chapter 1. For descriptions of the core
and common attributes, see Chapter 1.

Table 5-6: Attributes Inherited by the Simple Text Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

Determined by the geometry
manager
Determined by the geometry
manager

Attribute Name
Core Attributes

Dialog Box and Text Widget Functions 5-29

Table 5-6:

5.3.3

(continued)

Attribute Name

Data Type

Default

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Set as large as necessary to
display the DwtNrows with the
specified DwtNmarginWidth
As large as necessary to display
the DwtNcols with the
specified DwtNmarginHeight
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Widget-Specific Attributes
Table 5-7 lists the widget-specific attributes for the simple text widget.
Descriptions of these attributes follow the table.

Table 5-7: Widget-Specific Attributes for the Simple Text Widget
Attribute Name

Data Type

Default

DwtNmarginWidth
DwtNmarginHeight
DwtNcols
DwtNrows
DwtNtopPosition
DwtNwordWrap

Dimension
Dimension
Dimension
Dimension
DwtTextPosition
Boolean

2 pixels
Two pixels
20 characters
1 character
Zero
False

5-30 Dialog Box and Text Widget Functions

Table 5-7:

(continued)

Attribute Name

Data Type

Default

DwtNscrollVertical
DwtNresizeHeight
DwtNresizeWidth
DwtNvalue
DwtNeditable
DwtNmaxLength
DwtNfocusCallback
DwtNhelpCallback
DwtNlostFocusCallback
DwtNvalueChangedCallback
DwtNinsertionPointVisible
DwtNautoShowInsertPoint
DwtNinsertionPosition
DwtNforeground

Boolean
Boolean
Boolean
char *
Boolean
int
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackptr
DwtCallbackPtr
Boolean
Boolean
int
Pixel

False
True
True

DwtNfont
DwtNblinkRate
DwtNscrollLeftSide
DwtNhalfBorder
DwtNpendingDelete
DwtNuserData

DwtFontList
int
Boolean
Boolean
Boolean
Opaque *

True
2**31-1

NULL
NULL
NULL
NULL
True
True
Zero
The current server's default
foreground
The current server font list.
500 milliseconds
False
True
True

NULL

DwtNmarginWidth Specifies the number of pixels between the left or
right edge of the window and the text.
DwtNmarginHeight Specifies the number of pixels between the top or
bottom edge of the window and the text.
DwtNcols

Specifies the width of the text window measured in
character spaces.

DwtNrows

Specifies the height of the text window measured in
character heights or number of line spaces.

DwtNt opP 0 sit i on Specifies the position to display at the top of the
window.
DwtNwordWrap

Specifies a boolean value that, when True,
indicates that lines are broken at word breaks and
text does not run off the right edge of the window.

DwtNscrollVertical
Specifies a boolean value that, when True, adds a
scroll bar that allows the user to scroll vertically
through the text.
Dialog Box and Text Widget Functions 5-31

DwtNresizeHeight Specifies a boolean value that, when True,
indicates that the simple text widget will attempt to
resize its height to accommodate all the text
contained in the widget. If this is set to True, the
text will always be displayed starting from the first
position in the source, even if instructed otherwise.
This attribute is ignored if
DwtNscrollVerticalis True.
DwtNresizeWidth Specifies a boolean value that, when True,
indicates that the simple text widget will attempt to
resize its width to accommodate all the text
contained in the widget. This argument is ignored if
DwtNwordWrap is True.
DwtNvalue

Specifies the actual text to display.

DwtNeditable

Specifies a boolean value that, when True,
indicates that the user can edit the text string in the
simple text widget. If False, prohibits the user
from editing the text string.

DwtNmaxLength

Specifies the maximum length of the text string in
the simple text widget.

DwtNfocusCallbackSpecifies the callback function or functions called
when the simple text widget accepted the input focus.
For this callback, the reason is DwtCRFocus.
DwtNhelpCallback Specifies the callback function or functions called
when a help request is made.
DwtNlostFocusCallback
Specifies the callback function or functions called
when the simple text widget loses focus. For this
callback, the reason is DwtCRLostFocus.
DwtNvalueChangedCallback
Specifies the callback function or functions called
when the simple text widget value changed. For this
callback, the reason is DwtCRVal ueChanged.
DwtNinsertionPointVisible
Specifies a boolean value that, when True,
indicates that the insertion point is marked by a
blinking text cursor.
DwtNautoShowlnsertPoint
Specifies a boolean value that, when True, ensures
that the text visible in the simple text widget window

5-32 Dialog Box and Text Widget Functions

will contain the insertion point. This means that if
the insertion point changes, the contents of the
simple text widget window may scroll in order to
bring the insertion point into the window.
DwtNinsertionPosition
Specifies the current location of the insertion point.
DwtNforeground

Specifies the pixel for the foreground of the simple
text widget.

DwtNfont

Specifies the font list to be used for the simple text
widget.

DwtNblinkRate

Specifies the blink rate of the text cursor in
milliseconds.

DwtNscrollLeftSide
Specifies a boolean value that, when True,
indicates that the vertical scroll bar should be placed
on the left side of the simple text window. This
attribute is ignored if DwtNscroll Vertical is
False.
DwtNhalfBorder

Specifies a boolean value that, when True,
indicates that a border is displayed only on the left
and bottom edges of the simple text widget.

DwtNpendingDeleteSpecifies a boolean value that, when True,
indicates that selected text containing the insertion
point is deleted when new text is entered.
DwtNuserData

Specifies any user private data to be associated with
the widget. The XUI Toolkit does not interpret this
data.

5.4 Manipulating a Simple Text Widget
The XUI Toolkit provides you with some useful functions with which you
can manipulate the text widget. Specifically, these functions allow you to:
•

Clear the global selection

•

Obtain the global selected text

•

Set the global selected text

•

Obtain a text string

•

Display a new text string

•

Obtain the current maximum length of the text widget

Dialog Box and Text Widget Functions 5-33

5.4.1

•

Set the maximum length of the text widget

•

Obtain editing information about the text

•

Set the editing permission for the text

•

Replace part of the old text

Clearing, Obtaining, and Setting the Global Selection
To clear the global selection, use DwtSTextClearSelection.
void DwtSTextClearSelection (widget, time)
Widget widget;
Time time;

widget

Specifies the widget ID.

time

Specifies the time of the event that led to the call to
XSetSelectionOwner. You can pass either a timestamp
or Current Time. Whenever possible, however, use the
timestamp of the event leading to the call.

The DwtSTextClearSelection function clears the global selection
highlighted in the simple text widget.
To retrieve the global selection currently highlighted, use
DwtSTextGetSelection:
char *DwtSTextGetSelection (widget)
Widget widget;

widget

Specifies the widget ID.

The DwtSTextGetSelection function retrieves the text currently
highlighted (selected) in the simple text widget. It returns a NULL-pointer if
no text is selected in the widget. The application is responsible for freeing
the storage associated with the string by calling XtFree.
To set the selected global text into the widget, use
DwtSTextGetSelection:
void DwtSTextSetSelection (widget, first, last, time)
Widget widget;
int first, last;
Time time;

widget

Specifies the widget ID.

first

Specifies the first character position of the selected string.

last

Specifies the last character position of the selected string.

5-34 Dialog Box and Text Widget Functions

time

Specifies the time of the event that led to the call to
XSetSelectionOwner. You can pass either a timestamp
or CurrentTime. Whenever possible, however, use the
timestamp of the event leading to the call.

The DwtSTextSetSelection function makes the specified text in the
simple text widget the current global selection and highlights it in the simple
text widget. Within the text window, first marks the first character position
and last marks the last position. The field characters are numbered in
sequence starting at O.

5.4.2

Obtaining and Displaying a New Text String
To obtain the pointer to the currently displayed string, use
DwtSTextGetString:
char

widget

* DwtSTextGetString (widget)
Widget widget;
Specifies the ID of the simple text widget

The DwtSTextGetString function returns a pointer to the current string
in the simple text widget window. The application is responsible for freeing
the storage associated with the string by calling XtFree.
To set the text string in the simple text widget, use
DwtSTextSetString:
void DwtSTextSetString (widget, value)
Widget widget;
char * value;

widget

Specifies the ID of the simple text widget whose text string
you want to set.

value

Specifies the text that replaces all text in the current text
widget window.

The DwtSTextSetString function completely changes the string in the
simple text widget.

5.4.3

Obtaining and Setting the Maximum Length of the Simple
Text Widget
To obtain the current maximum allowable length of the text string in the
simple text widget, use DwtSTextGetMaxLength:

Dialog Box and Text Widget Functions 5-35

int DwtSTextGetMaxLength (widget)
Widget widget;

widget

Specifies the ID of the simple text widget whose maximum
text string length you want to obtain.

The DwtSTextGetMaxLength function returns the current maximum
allowable length of the text string in the simple text widget.
To set the maximum length of the text string in the simple text widget, use
DwtSTextSetMaxLength:
void DwtSTextSetMaxLength (widget, max_length)
Widget widget;
int max_length;

widget

Specifies the ID of the simple text widget whose maximum
text string length you want to set.
Specifies the maximum length of the text string in the simple
text widget. This argument sets the DwtNmaxLength
attribute associated with DwtSTextCreate.

The DwtSTextSetMaxLength function sets the maximum allowable
length of the text in the simple text widget and prevents the user from
entering text larger than this limit.

5.4.4

Obtaining and Setting Editing Information About the Text
To obtain the edit-permission-state in the simple text widget, use
DwtSTextGetEditable:
Boolean DwtSTextGetEdi table (widget)
Widget widget;

widget

Specifies the ID of the simple text widget whose edit
permission state you want to obtain.

The DwtSTextGetEdi table function returns the current editpermission-state, which indicates whether the user can edit the text in the
simple text widget. If the function returns True, the user can edit the string
text in the simple text widget. If it returns False, the user cannot edit the
text.
To set the edit permission state in the simple text widget, use
DwtSTextSetEditable:

5-36 Dialog Box and Text Widget Functions

void DwtSTextSetEdi table (widget, editable)
Widget widget;
Boolean editable;

widget

Specifies the ID of the simple text widget whose edit
permission state you want to set.

editable

Specifies a boolean value that, when True, indicates that
the user can edit the text string in the simple text widget. If
False, prohibits the user from editing the text string.

The DwtSTextSetEdi table function sets the edit permission state
information concerning whether the user can edit text in the simple text
widget.

5.4.5

Replacing Part of the Old Text
To replace part of the existing text string, use DwtSTextReplace:
void DwtSTextReplace (widget, jromyos, toyos, value)
Widget widget;
int fromyos, toyos;
DwtCompString value;

widget

Specifies the ID of the simple text widget whose text string
you want to replace.

jromyos

Specifies the beginning character position within the text
string marking the text being replaced.

toyos

Specifies the last character position within the text string
marking the text being replaced.

value

Specifies the text to replace part of the current text in the
simple text widget.

The DwtSTextReplace function replaces part of the text string in the
simple text widget. Within the window, the positions are numbered starting
from 0 and increasing sequentially. For example, to replace the second and
third characters in the string, jromyos should be 1 and to yos should be 3.
To insert a string after the fourth character,jromyos and to yos should both
be 4.

5.5 Creating a Compound String Text Widget
To create an instance of the compound string text widget, use DwtCSText
or DwtCSTextCreate. When calling DwtCSText, you set the
compound-string text widget attributes presented in the formal parameter list.
For DwtCSTextCreate, however, you specify a list of attribute
name/value pairs that represent all the possible compound-string text widget
Dialog Box and Text Widget Functions 5-37

attributes. After you create an instance of this widget, you can manipulate it
using the appropriate X intrinsics functions. A description of each follows:
Widget DwtCSText (parent_widget, name, x, y, eols, rows, value)

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the top of the widget
window relative to the inner upper left comer of the parent
window. This argument sets the DwtNy core widget
attribute.

eols

Specifies the width of the text window measured in character
cells. This argument sets the DwtNcols attribute
associated with DwtCSTextCreate.

rows

Specifies the height of the text window measured in character
cells or number of lines. This argument sets the DwtNrows
attribute associated with DwtCSTextCreate.

value

Specifies the text contents of the compound-string text
widget. This argument sets the DwtNvalue attribute
associated with DwtCSTextCreate.

Widget DwtCSTextCreate (parent_widget, name,

override arglist, override_argeount)
-

Widget parent_widget;
char * name ;
ArgList override_arglist;
int override_argeount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argeount
Specifies the number of attributes in the application override
argument list (override _arglist).
The DwtCSText and DwtCSTextCreate functions create an instance of
a compound-string text widget and return its associated widget ID. The
compound-string text widget enables the application to display a single or
multiline field of text for input and editing by the user. By default the text

5-38 Dialog Box and Text Widget Functions

window expands or shrinks as the user enters or deletes text characters. Note
that the text window does not shrink below the initial size set at creation
time.
The compound-string text widget does not support children; therefore, there
is no geometry or resize semantics.

5.5.1

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
char *charset;
unsigned int charset_1eni
DwtCSTextCallbackStructi

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRFocus

The compound-string text widget has
received the input focus.

DwtCRLostFocus

The compound-string text widget has lost
the input focus.

DwtCRVal ueChanged

The user changed the value of the text in
the compound-string text widget.

DwtCRHelpRequested

The user selected Help.

DwtCRNoFont

The widget font list contained no entry for
the required character set.

The event member is a pointer to the Xlib structure XEvent, which
describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding.
The charset member is set to the character set ill for which the widget has no
matching font in its font list. The callback should modify the widget font list
to include an entry for the required character set.
The charset_Ien member is set to the length of the charset string.

Dialog Box and Text Widget Functions 5-39

5.5.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the simple text widget is:
•

core

•
•

text
cstext

Table 5-8 lists the attributes inherited by the compound string text widget.
For descriptions of the core attributes, see Chapter 1.

Table 5-8: Attributes Inherited by the Compound String Text
Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged

XtTranslations
int
XtTranslations
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Set as large as necessary to
display the DwtNrows and
DwtNcols with the specified
DwtNmarginWidthmd
DwtNmarginHeight
Set as large as necessary to
display the DwtNcols and
DwtNrows with the specified
DwtNmarginHeightmd
DwtNmarginWidth
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True

Core Attributes

~o Dialog Box and Text Widget Functions

Table 5-8:

5.5.3

(continued)

Attribute Name

Data Type

Default

DwtNscreen
DwtNdestroyCallback

Screen *
DwtCallbackptr

The parent screen
NULL

Widget-Specific Attributes
Table 5-9 lists the widget-specific attributes for the compound string text
widget. Descriptions of these attributes follow the table.

Table 5-9: Widget-Specific Attributes for the Compound String
Text Widget
Attribute Name

Data Type

Default

DwtNmarginWidth
DwtNmarginHeight
DwtNcols
DwtNrows
DwtNtopPosition
DwtNwordWrap
DwtNscrollVertical
DwtNresizeHeight
DwtNresizeWidth
DwtNvalue
DwtNeditable
DwtNmaxLength
DwtNfocusCallback
DwtNhelpCallback
DwtNlostFocusCallback
DwtNvalueChangedCallback
DwtNinsertionPointVisible
DwtNautoShowlnsertPoint
DwtNinsertionPosition
DwtNforeground

Dimension
Dimension
Dimension
Dimension
DwtTextPosition
Boolean
Boolean
Boolean
Boolean
char *
Boolean
int
DwtCallbackptr
DwtCallbackptr
DwtCallbackptr
DwtCallbackptr
Boolean
Boolean
int
Pixel

2 pixels
Two pixels
20 characters
1 character
Zero
False
False
True
True

DwtNfont

DwtFontList

DwtNblinkRate
DwtNscrollLeftSide

int
Boolean

True
2**31-1
NULL
NULL
NULL
NULL
True
True
Zero
The current server's default
foreground
The current server's
DwtFontList
500 milliseconds
False

Dialog Box and Text Widget Functions 5-41

Table 5-9:

(continued)

Attribute Name

Data Type

Default

DwtNhalfBorder
DwtNpendingDelete
DwtNdirectionRToL
DwtNtextPath
DwtNeditingPath
DwtNbidirectionalCursor
DwtNnofontCallback

Boolean
Boolean
unsigned char
int
int
Boolean
DwtCallbackPtr

True
True
DwtDirectionRightDown
Left to right
Left to right
False

NULL

Specifies the width of the text window measured in
character spaces.

DwtNrows

Specifies the height of the text window measured in
character heights or number of line spaces.

DwtNtopPosi tion Specifies the position to display at the top of the
window.
DwtNwordWrap

Specifies a boolean value that, when True,
indicates that lines are broken at word breaks and
text does not run off the right edge of the window.

DwtNscrollVertical
Specifies a boolean value that, when True, adds a
scroll bar that allows the user to scroll vertically
through the text.
DwtNresizeHeight Specifies a boolean value that, when True,
indicates that the compound-string text widget resizes
its height to accommodate all the text contained in
the widget. If this is set to True, the text will
always be displayed starting from the first position in
the source, even if instructed otherwise. This
attribute is ignored if DwtNscroll Vertical is
True.
DwtNresizeWidth Specifies a boolean value that, when True,
indicates that the compound-string text widget resizes
its width to accommodate all the text contained in
the widget. This argument is ignored if

5-42 Dialog Box and Text Widget Functions

DwtNwordWrap is True.
DwtNvalue

Specifies the text contents of the compound-string
text widget. If you accept the default of NULL, the
text path and editing path are set to
DwtDirectionRightDown. Otherwise, the text
path and editing path are set from the direction of the
first segment of the value.

DwtNeditable

Specifies a boolean value that, when True,
indicates that the user can edit the text in the
compound-string text widget. If False, prohibits
the user from editing the text.

DwtNmaxLength

Specifies the maximum length of the text string, in
characters, in the compound-string text widget.

DwtNfocusCallbackSpecifies the callback function or functions called
when the compound-string text widget accepted the
input focus. For this callback, the reason is
DwtCRFocus.
DwtNhelpCallback Specifies the callback function or functions called
when a help request is made. For this callback, the
reason is DwtCRHelpRequested.
DwtNlostFocusCallback
Specifies the callback function or functions called
when the compound-string text widget loses input
focus. For this callback, the reason is
DwtCRLostFocus.
DwtNvalueChangedCallback
Specifies the callback function or functions called
when the value of the compound-string text widget
changes. For this callback, the reason is
DwtCRValueChanged.
DwtNinsertionPointVisible
Specifies a boolean value that, when True,
indicates that the insertion point is marked by a
blinking text cursor.
DwtNautoShowlnsertPoint
Specifies a boolean value that, when True, ensures
that the text visible in the compound-string text
widget window contains the insertion point. This
means that if the insertion point changes, the
contents of the compound-string text widget window
might scroll in order to bring the insertion point into
the window.

Dialog Box and Text Widget Functions 5-43

DwtNinsertionPosition
Specifies the current location of the insertion point.
DwtNforeground

Specifies the pixel for the foreground of the
compound-string text widget.

DwtNfont

Specifies the font list to be used for the compoundstring te~t widget.
Specifies the blink rate of the text cursor in
milliseconds.

DwtNblinkRate

DwtNscrollLeftSide
Specifies a boolean value that, when True,
indicates that the vertical scroll bar should· be placed
on the left side of the compound-string text window.
This attribute is ignored if
DwtNscroll Vertical is False.
DwtNhal fBorder

Specifies a boolean value that, when True,
indicates that a border is displayed only on the
starting edge and bottom edge of the compoundstring text widget.

DwtNpendingDeleteSpecifies a boolean value that, when True,
indicates that selected text containing the insertion
point is deleted when new text is entered.
DwtNdirectionRToLSpecifies the direction in which the text is drawn
and wraps. You can pass
DwtDirectionLeftDown (text is drawn from left
to right and wraps down);
DwtDirectionRightUp (text is drawn from left
to right and wraps up);
DwtDirectionLeftDown (text is drawn from
right to left and wraps down); or
DwtDirectionLeftUp (text is drawn from right
to left and wraps up). The DwtNdirectionRToL
attribute only affects the direction toward which the
window is resized.
DwtNtextPath

Specifies a read-only value that holds the main text
path (direction) of the text in the compound-string
text widget. It is set from the initial compoundstring value of the widget. This attribute is used
only if DwtNvalue is NULL.

DwtNedi tingPath Specifies a read-only value that holds the current
editing text path (direction) in the compound-string
text widget. It is set initially equal to
DwtNtextPath. This attribute is used only if

5-44 Dialog Box and Text Widget Functions

DwtNval ue is NULL.
DwtNbidirectionalCursor
Specifies a boolean value that, when True,
indicates that the shape of the cursor at the insertion
point will be dependent on the current editing
direction.
DwtNnofontCallback
Specifies a callback function called when the
compound-string text widget has failed to find a font
needed for the display of a text tagged by a specific
character set. For this callback, the reason is
DwtCRNoFont.

5.6 Manipulating a Compound String Text Widget
The XUI Toolkit provides you with some useful functions with which you
can manipulate the compound string text widget. Specifically, these
functions allow you to:

5.6.1

•

Clear the global selection

•

Obtain and set the global selected compound string text

•

Obtain and display a compound string text

•

Obtain and set the current maximum length of the compound string text
widget

•

Obtain and set editing information about the compound string text
widget

•

Replace part of the old compound string text widget

Clearing, Obtaining, and Setting the Global Selection
To clear the global selection in the compound string text widget, use
DwtCSTextClearSelection.
void DwtCSTextClearSelection (widget, time)
Widget widget;
Time time;

widget

Specifies the ID of the compound-string text widget.

time

Dialog Box and Text Widget Functions 5-45

The DwtCSTextClearSelection function clears the global selection
highlighted in the compound-string text widget.
To retrieve the global selection in the compound string text widget, use
DwtCSTextGetSelection.
DwtCompString DwtCSTextGetSelection (widget)
Widget widget;

widget

Specifies the ID of the compound-string text widget.

The DwtCSTextGetSelection function retrieves the text currently
highlighted (selected) in the compound string text widget. It returns a NULL
pointer if no text is selected in the widget. The application is responsible for
freeing the storage associated with the text by calling XtFree.
To set the specified text in the compound string text widget, use
DwtCSTextSetSelection.
void DwtCSTextSetSelection (widget, first,
Widget widget;
int first, last;
Time time;

last, time)

widget

Specifies the ID of the compound-string text widget.

first

Specifies the first character position of the selected
compound-string text.

last

Specifies the last character position of the selected
compound-string text.

time

The DwtCSTextSetSelection function makes the specified text in the
compound-string text widget the current global selection and highlights it in
the compound-string text widget. Within the text window, first marks the
first character position and last marks the last position. The field characters
start at 0 and increase sequentially.

5.6.2

Obtaining and Displaying a New Compound String Text
To retrieve all the text from the compound string text widget, use
DwtCSTextGetString.

5-46 Dialog Box and Text Widget Functions

DwtCompString DwtCSTextGetString (widget)
Widget widget;

widget

Specifies the ID of the compound-string text widget.

The DwtCSTextGetString function retrieves the current compoundstring from the compound-string text widget. The application is responsible
for freeing the storage associated with the string by calling XtFree.
To set the text in the compound string text widget, use
DwtCSTextSetString.
void DwtCSTextSetString (widget, value)
Widget widget;
DwtCompString value;

widget

Specifies the ID of the compound-string text widget.

value

Specifies the text that replaces all text in the current
compound-string text widget.

The DwtCSTextSetString function completely changes the text in the
compound-string text widget.

5.6.3

Obtaining and Setting the Maximum Length of the
Compound String Text Widget
To obtain the maximum length of the text in the compound string text
widget, use DwtCSTextGetMaxLength.
int DwtCSTextGetMaxLength (widget)
Widget widget;

widget

Specifies the ID of the compound-string text widget.

The DwtCSTextGetMaxLength function returns the current maximum
allowable length of the text in the compound-string text widget.
To set the maximum length of the text in the compound string text widget,
uoo DwtCSTextSetMaxLength.
void DwtCSTextSetMaxLength (widget, max_length)
Widget widget;
in t max_length;

widget

Specifies the ID of the compound-string text widget.

max_length

Specifies the maximum length, in characters, of the text in
the compound string text widget. This argument sets the
DwtNmaxLength attribute associated with
DwtCSTextCreate.

Dialog Box and Text Widget Functions 5-47

The DwtCSTextSetMaxLength function sets the maximum allowable
length of the text in the compound-string text widget and prevents the user
from entering text longer than this limit.

5.6.4

Obtaining and Setting Editing Information About the
Compound String Text Widget
To obtain the edit permission state in the compound string text widget, use
DwtCSTextGetEditable.
Boolean DwtCSTextGetEdi table (widget)

widget
Specifies the ID of the compound-string text widget.
The DwtCSTextGetEdi table function returns the current editpermission-state, which indicates whether the user can edit the text in the
compound-string text widget. If the function returns True, the user can edit
the string text in the compound-string text widget. If it returns False, the
user cannot edit the text.
To set the edit permission state in the compound string text widget, use
DwtCSTextSetEditable.
void DwtCSTextSetEdi table (widget, editable)
Widget widget;
Boolean editable;

widget

Specifies the ID of the compound-string text widget.

editable

Specifies a boolean value that, when True, indicates that
the user can edit the text in the compound-string text widget.
If False, prohibits the user from editing the text.

The DwtCSTextSetEditable function sets the edit permission state
information concerning whether the user can edit text in the compound-string
text widget.

5.6.5

Replacing Part of the Old Text in the Compound String Text
Widget
To replace part of the existing text in the compound string text widget, use
DwtCSTextReplace.
void DwtCSTextReplace (widget, from yos, to yos, value)
Widget widget;
int from yos, to yos;
DwtCompString value;

5-48 Dialog Box and Text Widget Functions

widget

Specifies the ID of the compound-string text widget.

fromyos

Specifies the first character position of the compound-string
text being replaced.

toyos

Specifies the last character position of the compound-string
text being replaced.

value

Specifies the text to replace part of the current text in the
compound-string text widget.

The DwtCSTextReplace function replaces part of the text in the
compound-string text widget. Within the widget, positions are numbered
starting at 0 and increasing sequentially. For example, to replace the second
and third characters in the text, from yos should be 1 and toyos should be
3. To insert text after the fourth character,/romyos and to yos should both
be 4.

5.7 Creating a Color Mix Widget
To create an instance of the color mix widget, use DwtColorMixCreate.
When calling DwtColorMixCreate, you specify a list of attribute
name/value pairs that represents all the possible color mixing widget
attributes. After you create an instance of this widget, you can manipulate it
using the appropriate X intrinsics functions. A description of each follows:
Widget DwtColorMixCreate (parent widget, name,

override_argUst, override_argcount)
Widget parent_widget;
char *name;
ArgList override_argUst;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _argUst).
The color mixing widget is a composite widget; that is, it is composed of a
parent widget and several child widgets at creation time. The parent widget
is a pop-up dialog box that has some labels, handles geometry management,
calls back to the application and contains the following child widgets by
default:
•

A color display subwidget that displays the colors being mixed

Dialog Box and Text Widget Functions 5-49

•

A color mixer subwidget that allows the user to specify colors

•

An optional work area widget

While the color mixing widget contains these three child widgets by default,
the application can replace either or both the color display and color mixer
subwidgets. Thus, applications can provide any type of color display or
color mixer tool model.
The default color display widget displays both the original color (the color
value supplied by the application when the mixing began) and the current
new color. Applications can set the following values:
•

The original color values for red, green, and blue

•

The new color values for red, green, and blue

•

The background color of the display widget

•

The dimensions of the color display windows and background area

If the display device is a gray scale, pseudo color, or static color device, the
color display widget allocates a maximum of three color cells whenever it
becomes managed. If fewer than three color cells are available, the order of
precedence is as follows:

Original color cell

New color cell

Background color cell

These color cells are deallocated whenever the widget becomes unmanaged.
If an application replaces the default color display sub widget, the application
may provide a function to allow the color mixing widget to pass the current
new color value from the color mixer subwidget. Otherwise, the color
mixing widget cannot inform the color display subwidget of color changes.
The application can return to the default color display subwidget at any time
by using XtSetValues to set DwtNdisplayWindow to NULL.

The default ROB color mixer subwidget provides three scales, each of which
represents a percentage of red, green, and blue. Users may also type in the
actual X color values (0 to 65535) in the entry fields. When color mixing
begins, the color mixer subwidget is set to the current new color values.
If an application replaces the default color mixer subwidget, the new color
mixer subwidget must inform the color mixing widget of changes to the
current color value. The fastest way to do this is to call the convenience
function DwtColorMixSetNewColor, although you can also use
XtSetValues. The application can return to the default color mixer
subwidget at any time by using XtSetVal ues to set
DwtNmixerWindow to NULL.

5-50 Dialog Box and Text Widget Functions

Note that setting DwtNdisplayWindowand DwtNmixerWindow to
NULL when the color mixing widget is created results in no color display
subwidget and no color mixer subwidget. Setting these attributes to NULL
after the color mixing widget is created results in returning to the default
color display and color mixer subwidgets.
The color mixing widget runs on any XUI display device. On gray scale
devices, the default color display subwidget shows the ROB values in gray
scale. On static gray (monochrome) devices, the default color display
subwidget is not visible.
As far as geometry management is concerned, the color mixing widget
conforms to the size of its children.
As far as resizing is concerned, the color mixing widget uses the dialog box
shrink wrap mode. It expands and shrinks relative to the size of its children.

5.7.1

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
unsigned short newredi
unsigned short newgrn;
unsigned short newblui
unsigned short origred;
unsigned short origgrn;
unsigned short origblu;
DwtColorMixCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActivate

The user has activated the OK push button.

DwtCRApply

The user has selected the Apply push
button.

DwtCRCancel

The user has activated the Cancel push
button.

Dialog Box and Text Widget Functions 5-51

The newred member is set to the new red color value for the color mix
widget. The newgrn member is set to the new green color value for the color
mix widget. The newblu member is set to the new blue color value for the
color mix widget.
The origred member is set to the original red color value for the color mix
widget. The origgm member is set to the original green color value for the
color mix widget. The origblu member is set to the original blue color value
for the color mix widget.

5.7.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the color mix widget is:
•
•

core
composite

•

constraint

•

dialog

Table 5-10 lists the attributes inherited by the color mix widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 5-10: Attributes Inherited by the Color Mix Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators

XtTranslations

Determined by the geometry
manager
Determined by the geometry
manager
Zero pixels
Zero pixels
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL

Core Attributes

5-52 Dialog Box and Text Widget Functions

Table 5-10:

(continued)

Attribute Name

Data Type

Default

DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Depth of the parent window
NULL
True
The parent screen
NULL

Dialog Box Pop-Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback
DwtNunits
DwtNstyle
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNnoResize
DwtNtitle
DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr
unsigned char
unsigned char
DwtCallbackPtr
XtTranslations
Dimension
Dimension
Boolean
Boolean
unsigned char
Boolean
DwtCompString
DwtCallbackptr
DwtCallbackptr
Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton
DwtNgrabKeySyms

Boolean
Widget
Widget
KeySym

DwtNgrabMergeTranslations

XtTranslations

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL
DwtFontUnits
DwtModeless
NULL
NULL
10 pixels
10 pixels
False
True
DwtResizeShrinkWrap
True
"Color Mixing"
NULL
NULL
True for modal dialog box
False for modeless dialog box
False
NULL
NULL
The default array contains the Tab
key symbol.
The default syntax is:
"-Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSNEXTO\n\
Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSPREVO";

Dialog Box and Text Widget Functions 5-53

5.7.3

Widget-Specific Attributes
Table 5-11 lists the widget-specific attributes for the color mix widget.
Descriptions of these attributes follow the table.

Table 5-11: Widget-Specific Attributes for the Color Mix Widget
Attribute Name

Data Type

Default

DwtNmainLabel
DwtNdisplayLabel
DwtNmixerLabel
DwtNorigRedValue
DwtNorigGreenValue
DwtNorigBlueValue
DwtNnewRedValue

DwtCompString
DwtCompString
DwtCompString
unsigned short
unsigned short
unsigned short
unsigned short

DwtNnewGreenValue

unsigned short

DwtNnewBlueValue

unsigned short

DwtNdisplayWindow

Widget

DwtNsetNewColorProc

char *

DwtNmixerWindow

Widget

DwtNworkWindow
DwtNokLabel
DwtNapplyLabel
DwtNresetLabel
DwtNcancelLabel

Widget
DwtCompString
DwtCompString
DwtCompString
DwtCompString

NULL
NULL
NULL
Zero
Zero
Zero
Zero, unless
DwtNmatchColors is True,
in which case
DwtNnewRedVal ue is set to
match DwtNorigRedValue
whenever the widget is created
and mapped.
Zero, unless
DwtNmatchColors is True,
in which case
DwtNnewGreenVal ue is set to
ma~h DwtNorigGreenValue
whenever the widget is created
and mapped.
Zero, unless
DwtNmatchColors is True,
in which case
DwtNnewBlueValue is set to
ma~h DwtNorigBlueValue
whenever the widget is created
and mapped.
The color mixing widget display
subwidget
The function used by the color
mixing widget to update the new
color values displayed in the color
display subwidget.
The color mixing widget's RGB
color mixer subwidget
NULL
"OK"
"Apply"
"Reset"
"Cancel"

5-54 Dialog Box and Text Widget Functions

Table 5-11:

(continued)

Attribute Name

Data Type

Default

DwtNokCallback
DwtNapplyCallback
DwtNcancelCallback
DwtNmatchColors

DwtCallbackPtr
DwtCallbackPtr
DwtCallbackptr
Boolean

DwtNresize

unsigned short

DwtNbackGreenValue

unsigned short

DwtNbackBlueValue

unsigned short

DwtNdisplayColWinWidth

Dimension

DwtNdisplayColWinHeight

Dimension

DwtNdispWinMargin

Dimension

DwtNsliderLabel

DwtCompString

DwtNvalueLabel

DwtCompString

DwtNredLabel

DwtCompString

NULL
NULL
NULL
True
This attribute can be set only if
the default color display widget is
used.
Gray (32767)
This attribute can be set only if
the default color display widget is
used.
Gray (32767)
This attribute can be set only if
the default color display widget is
used.
Gray (32767)
This attribute can be set only if
the default color display widget is
used.
80 pixels
This attribute can be set only if
the default color display widget is
used.
80 pixels
This attribute can be set only if
the default color display widget is
used.
20 pixels
This attribute can be set only if
the default color display widget is
used.
"Percentage"
This attribute can be set only if
the default color mix tool widget
is used.
"Value"
This attribute can be set only if
the default color mix tool widget
is used.
"Red"
This attribute can be set only if
the default color mix tool widget
is used.

Dialog Box and Text Widget Functions 5-55

Table 5-11:

(continued)

Attribute Name

Data Type

Default

DwtNgreenLabel

DwtCompString

DwtNblueLabel

DwtCompString

"Green"
This attribute can be set only if
the default color mix tool widget
is used.
"Blue"
This attribute can be set only if
the default color mix tool widget
is used.

DwtNmainLabel

Specifies the text of the main label, which is centered
at the top of the color mixing widget.

DwtNdisplayLabel Specifies the text of the label centered above the
color display widget.
DwtNmixerLabel

Specifies the text of the label centered color mixing
widget.

DwtNorigRedValue Specifies the original red color value for the color
mixing widget. Applications should set the original
red value.
DwtNorigGreenValue
Specifies the original green color value for the color
mixing widget. Applications should set the original
green value.
DwtNorigBl ueVal ueSpecifies the original blue color value for the color
mixing widget. Applications should set the original
blue value.
DwtNnewRedVal ue Specifies the new red color value for the color
mixing widget.
DwtNnewGreenVal ueSpecifies the new green color value for the color
mixing widget.
DwtNnewBl ueVal ue Specifies the new blue color value for the color
mixing widget.
DwtNdisplayWindowSpecifies the color display widget. Setting this
attribute to NULL at widget creation time causes the
color display widget to not be displayed.
If an application substitutes its own color display
widget for the default color display widget, the
application is responsible for managing the widget,

5-56 Dialog Box and Text Widget Functions

that is, making it visible and controlling its geometry
management. An application can return to the
default color display widget by using
XtSetValues to set this attribute to NULL.
DwtNsetNewColorProc

Specifies the function used by the color mixing
widget to update the new color values displayed in
the color display subwidget. If the application
replaces the default color display subwidget and
wants the color mixing widget to update the new
color, the application must set this attribute.
Otherwise, replacing the default color display
subwidget sets this attribute to NULL.
DwtNmixerWindow Specifies the color mixer subwidget. The default

color mixer subwidget is based on the red, green, and
blue (RGB) color model. Setting this attribute to
NULL at widget creation time causes the color mixer
subwidget to not be displayed.
If an application substitutes its own color mixer
subwidget for the default color mixer subwidget, the
application is responsible for managing the widget,
that is, making it visible and controlling its geometry
management. An application can later return to the
default color mixer subwidget by using
XtSetValues to set this attribute to NULL.
Applications that use the default color mixer
subwidget need not worry about updating the new
color. However, applications that provide their own
color mixer subwidget are responsible for updating
the new color. Applications can do this by using
either XtSetValues or
DwtColorMixSetNewColor. Using
DwtColorMixSetNewColor is recommended
because it is more efficient.
DwtNworkWindow

Specifies an optional work area widget. If this
attribute is set and the application manages this
widget, the work window is placed below the color
display and color mixer sub widgets (if present) and
above the color mixing widget push buttons.

DwtNokLabel

Specifies the label for the OK push button.

DwtNapplyLabel

Specifies the label for the Apply push button.

Dialog Box and Text Widget Functions 5-57

DwtNresetLabel

Specifies the label for the Reset push button.

DwtNcancelLabel Specifies the label for the Cancel push button.
DwtNokCallback

Specifies the callback function or functions called
when the user clicks on the OK push button. For
this callback, the reason is DwtCRActi vate.

DwtNapplyCallbackSpecifies the callback function or functions called
when the user clicks on the Apply push button. For
this callback, the reason is Dwt CRApp I y .
DwtNcancelCallback
Specifies the callback function or functions called
when the user clicks on the Cancel button. For this
callback, the reason is DwtCRCancel.
DwtNmatchColors Specifies a boolean value that, when True,
indicates that the new color values are matched to
original color values. If False, new color values
are not matched to original color values.
This attribute can be set only if the default color
display widget is used.
DwtNbackRedValue Specifies the default color display widget's red
background color. This attribute can be set only if
the default color display widget is used.
DwtNbackGreenValue
Specifies the default color display widget's green
background color. This attribute can be set only if
the default color display widget is used.
DwtNbackBlueValueSpecifies the default color display widget's blue
background color. This attribute can be set only if
the default color display widget is used.
DwtNdisplayColWinWidth
Specifies the width of the original and new color
display windows. This attribute can be set only if
the default color display widget is used.
DwtNdisplayColWinHeight
Specifies the height of the original and new color
display windows. This attribute can be set only if
the default color display widget is used.
DwtNdispWinMarginSpecifies the margin between the original and the
new color display windows and the edge of the color
display widget. The margin is the area affected by
the background attributes (set gray by default).

5-58 Dialog Box and Text Widget Functions

This attribute can be set only if the default color
display widget is used.
DwtNsliderLabel Specifies the text of the label above the slider

representing the RGB scales. This attribute can be
set only if the default color mix tool widget is used.
DwtNvalueLabel

Specifies the text of the label above the RGB text
entry fields. This attribute can be set only if the
default color mix tool widget is used.

DwtNredLabel

Specifies the label for the ROB red scale widget.
This attribute can be set only if the default color mix
tool widget is used.

DwtNgreenLabel

Specifies the label for the RGB green scale widget.
This attribute can be set only if the default color mix
tool widget is used.

DwtNbl ueLabel

Specifies the label for the RGB blue scale widget.
This attribute can be set only if the default color mix
tool widget is used.

5.8 Manipulating a Color Mix Widget
The XUI Toolkit provides you with some useful functions with which you
can manipulate the color mix widget. Specifically, these functions allow you
to obtain and set the red, green, and blue color values.
To obtain the red, green, and blue color values for the color mix widget, use
DwtColorMixGetNewColor.
void DwtColorMixGetNewColor (cmw, red, green, blue)
Widget cmWi
unsigned short * red i
unsigned short * green i
unsigned short *bfuei
cmw

Specifies the widget ID of the color mixing widget.

red

Specifies the current new color red value.

green

Specifies the current new color green value.

blue

Specifies the current new color blue value.
See the section on colormap functions in the Guide to the
Xlib Library: C Language Binding for more information on
X color values.

The DwtColorMixGetNewColor function allows the color mixing
widget to pass the current color value created by the color mixer subwidget

Dialog Box and Text Widget Functions 5-59

to the color display subwidget. If the application uses the default color mixer
subwidget, using DwtColorMixGetNewColor is faster than using
XtGetValues.
To set the red, green, and blue color values in the color mix widget, use
DwtColorMixSetNewColor.
void DwtColorMixSetNewColor (cmw, red, green, blue)
Widget cmw;
unsigned short red;
unsigned short gnen;
unsigned short bfue;

cmw

Specifies the widget ID of the color mixing widget.

red

Specifies the new color red value. You can express the value
in percentages or by the X color values (0 to 65535).

green

Specifies the new color green value. You can express the
value in percentages or by the X color values (0 to 65535).

blue

Specifies the new color blue value. You can express the
value in percentages or by the X color values (0 to 65535).
See the section on colormap functions in the Guide to the
Xlib Library: C Language Binding for more information on
X color values.

The DwtColorMixSetNewColor function allows the user-supplied color
mixer subwidget to pass the current color values to the color mixing widget.
Using DwtColorMixSetNewColor is more efficient than using
XtSetValues.

5.9 Creating a List Box Widget
A list box displays a number of choices, such as names of available files,
from which the user can choose. The list box consists of items within a
rectangular area and a scroll bar to the right of those items. The user views
the items by operating the scroll bar. To create an instance of the list box
widget, use DwtListBox or DwtListBoxCreate.
When calling DwtListBox, you set the list box widget attributes presented
in the parameter list. For DwtListBoxCreate, however, you specify a
list of attribute name/value pairs that represent all the possible list box widget
attributes.
Mter you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions. A description of each follows:

5-60 Dialog Box and Text Widget Functions

Widget DwtListBox (parent_widget, name, x, y,
items, item count, visible items count,
callback, help callback, resize, - horiz)
Widget parent_widget;
char * name;
Position x, y;
DwtCornpString * items;
int item count, visible items count;
DwtCallbackptr callback, -help_callback;
Boolean resize;
Boolean horiz;

parent_widget Specifies the parent widget ID.
name
Specifies the name of the created widget.
x

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

items

Specifies the list of items to be displayed by the list box
widget. The list of items must be unique. This argument
sets the DwtNi terns attribute associated with
DwtListBoxCreate.

item count

Specifies the total number of items in the list. This argument
sets the DwtNi terns Count associated with
DwtListBoxCreate.

visible items count
Specifies the maximum number of visible items contained in
the list box. For example, if DwtNi ternsCount is 20, but
DwtNvisiblelternsCount is 5, only 5 items are visible
at anyone time. This argument sets the
DwtNvisiblelternsCount attribute associated with
DwtListBoxCreate.
Specifies the callback function or functions called when
callback
single callback, single confirm callback, extend callback, and
extend confirm callback functions are activated. This
argument sets the DwtNsingleCallback,
DwtNsingleConfirrnCallback,
DwtNextendCallback,and
DwtNextendConfirrnCallback attributes associated
Dialog Box and Text Widget Functions 5-61

with DwtListBoxCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
resize

Specifies a boolean value that, when True, indicates the list
box increases its width to accommodate items too wide to fit
inside the box. If False, the width remains constant unless
the caller changes the width by calling XtSetValues. If
you set DwtNresize to False, it is recommended that
you set DwtNhorizontal to True. This argument sets
the DwtNresize attribute associated with
DwtListBoxCreate.

horiz

Specifies a boolean value that, when True, indicates the list
box contains a horizontal scroll bar. If False, the list box
does not contain a horizontal scroll bar. A horizontal scroll
bar cannot be deleted or added to a list box after the list box
is created. This argument sets the
DwtNscrollHorizontal attribute associated with
DwtListBoxCreate.

Widget DwtListBoxCreate (parent widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char * name ;
ArgLi st override arglist;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Callback information

•

Geometry management and resizing

5-62 Dialog Box and Text Widget Functions

5.9.1

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callbac~ Information

The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
DwtCompString item;
int item_length;
int item_number;
DwtListBoxCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRSingle

The user selected a single item in the list by
clicking MB 1 on the item.

DwtCRSingleConfirm

The user selected a single item in the list
and confirmed another action to be taken
(by a callback) by double clicking on an
item. For example, a double click on a file
in the file selection box selects that file and
confirms another action to be taken.

DwtCRExtend

The user selected an item (by clicking MBI
on a single item while depressing the shift
key) while there is at .least one other
selected item. The user clicked MB 1 once
while pressing the Shift key on an item
when more than one is selected (multiple
selection callback).

DwtCRExtendConfirm

The user selected an item and confirmed
another action to be taken (by double
clicking MB 1 on a single item while
depressing the Shift key) while there is at
least one other selected item. This reason
applies only if DwtNsingleSelection
is True.

DwtCRHelpRequested

The user selected Help.

Dialog Box and Text Widget Functions 5-63

The event member is a pointer to the Xlib structure XEvent, which
describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding.
The item member is set to the last item selected when the callback occurred.
Note that only the last item, not all selected items, is returned. The
item_length member is set to the selected item's length when the callback
occurred. The item_number member is set to the item's position in the list
box when the callback occurred. The first position is one, not zero.

5.9.2

Geometry Management and Resizing
The list box widget does not support children; therefore, there is no geometry
semantics.
The size of the list box is determined by the following attributes in
descending precedence:
•

DwtNheight and DwtNwidth

•

DwtNyisibleltemsCount

•

DwtNresize

Setting the core attributes DwtNheight and DwtNwidth overrides the
widget-specific default settings. The following describes the sizing option.
The default list box height is determined by DwtNvisibleltemsCount.
Once set, the list box height will not change, regardless of the number of
items the list box actually contains, unless the core attribute DwtNheight
or the widget-specific attribute DwtNvisibleltemsCount is modified.
It is recommended that you control list box height by setting
DwtNvisibleltemsCount rather than DwtNheight.
The default list box width is controlled by the DwtNresize attribute. By
default, DwtNresize is True, and the list box increases its width to
accommodate items wider than its current width. However, the list box does
not shrink if wider items are removed. Note that only increases, not
decreases, in width are requested. The list box will not shrink if wider items
are removed. You can control this behavior with the DwtNresize
attribute. If DwtNresize is False, the width remains constant.
To keep the width of the list box constant, set DwtNwidth to the desired
width and set DwtNresize to False. In addition, set
DwtNhorizontal to True so that users can scroll the item list
horizontally to see items wider than the list box.

5-64 Dialog Box and Text Widget Functions

5.9.3

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the list box widget is:
•
•

core
composite

•
•

common
scroll window

•
list box
Based on this class hierarchy, the list box widget inherits attributes from the
core, composite, and common widgets. In addition, it inherits attributes from
the scroll window widget.
Table 5-12 lists the attributes inherited by the list box widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 5-12: Attributes Inherited by the List Box Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Set as large as necessary to hold
the longest item without
exceeding the size of its parent
Set as large as necessary to hold
the number of items specified by
DwtNvisibleltemsCount,
without exceeding the size of the
parent widget
One pixel
Default foreground color

DwtNaccelerators

XtTranslations

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL

Dialog Box and Text Widget Functions 5-65

Table 5-12:

(continued)

Attribute Name

Data Type

Default

DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
NOT SUPPORTED

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDo~

Scroll Window Attributes
DwtNhorizontalScrollBar
DwtNverticalScrollBar
DwtNworkWindow
DwtNshownValueAutomaticHoriz
DwtNshownValueAutomaticVert

5.9.4

Widget
Widget
Widget
Boolean
Boolean

NULL
NULL
NULL
True
False

Widget-Specific Attributes
Table 5-13 lists the widget-specific attributes for the list box widget.
Descriptions of these attributes follow the table.

Table 5-13: Widget-Specific Attributes for the List Box Widget
Attribute Name

Data Type

Default

DwtNmarginWidth
DwtNmarginHeight
DwtNspacing
DwtNitems
DwtNitemsCount

Dimension
Dimension
Dimension
DwtCompString *
int

10 pixels
4 pixels
1 pixel

5-06 Dialog Box and Text Widget Functions

NULL
Zero

Table 5-13:

(continued)

Attribute Name

Data Type

DwtNselectedltems
DwtNselectedltemsCount
DwtNvisibleltemsCount

DwtCompString *
int
int

DwtNsingleSelection
DwtNresize
DwtNhorizontal
DwtNsingleCallback
DwtNsingleConfirmCallback
DwtNextendCallback
DwtNextendConfirmCallback

Boolean
Boolean
Boolean
DwtCallbackptr
DwtCallbackPtr
DwtCallbackptr
DwtCallbackPtr

Default

NULL
Zero
As many items as can fit in the
core attribute DwtNheight.
The minimum is 1.
True
True
False

NULL
NULL
NULL
NULL

DwtNrnarginWidth Specifies the number of pixels between the border of
the widget window and the items. This attribute sets
the list box menu margin width.
DwtNrnarginHeight Specifies the number of pixels between characters of
each pair of consecutive items. This attribute sets
the list box menu margin height.
DwtNspacing

Specifies in pixels the spacing between list box
entries.

DwtNi terns

Specifies the list of items to be displayed by the list
box widget. The list of items must be unique. When
modifying DwtNiterns, always update
DwtNi ternsCount and
DwtNselectedlternsCount. When
DwtNiterns is NULL, DwtNiternsCount and
DwtNselectedlternsCount must be zero.

DwtNiternsCount

Specifies the total number of items in the list. When
DwtNi ternsCount is zero, DwtNi terns does not
have to be NULL. The list box widget uses
DwtNiternsCountand
DwtNselectedlternsCount, not DwtNi terns,
to determine if the list contains any items.
Therefore, you must specify DwtNiternsCount
whenever you modify DwtNi terns.

DwtNselectedlternsSpecifies the list of items that are selected in the list
box. The last selected item is visible in the list box.

Dialog Box and Text Widget Functions 5-67

DwtNselectedlternsCount
Specifies the number of items selected in the list box.
When DwtNselectedlternsCount is zero,
DwtNselectedlterns does not have to be NULL.
The list box uses DwtNselectedlternsCount
not DwtNselectedlterns to determine if the list
contains any selected items. Therefore, you must
specify DwtNselectedlternsCount whenever
you modify DwtNselectedlterns.
DwtNvisiblelternsCount
Specifies the maximum number of visible items
contained in the list box. For example, if
DwtNi ternsCount is 20, but
DwtNvisiblelternsCount is 5, only 5 items are
visible at anyone time.

The list box widget is designed so that its height is
based on DwtNvisiblelternsCount. Therefore,
it is preferable to control the list box height by using
DwtNvisiblelternsCount rather than
DwtNheight.
Applications that control list box height through the
core attribute DwtNheight are responsible for
handling font changes.
DwtNsingleSelection
Specifies a boolean value that, when True,
indicates only one item can be selected at a time.
DwtNresize

Specifies a boolean value that, when True,
indicates the list box increases its width to
accommodate items too wide to fit inside the box. If
Fa 1 s e, the width remains constant unless the caller
changes the width by calling XtSetValues. If
you set DwtNresize to False, it is
recommended that you set DwtNhorizontal to
True.

DwtNhorizontal

Specifies a boolean value that, when True,
indicates the list box contains a horizontal scroll bar.
If Fa 1 s e, the list box does not contain a horizontal
scroll bar. A horizontal scroll bar cannot be deleted
or added to a list box after the list box is created.

DwtNsingleCallback
Specifies the callback function or functions called
when the user selects a single item by clicking MB 1
on a single item. For this callback, the reason is
DwtCRSingle.
5-68 Dialog Box and Text Widget Functions

DwtNsingleConfirmCallback
Specifies the callback function or functions called
when the user double clicked MB 1 on an item. For
this callback, the reason is
DwtCRSingleConfirm.
DwtNextendCallback
Specifies the callback function or functions called
when the user single clicks MB 1 while depressing
the Shift key when more than one item is selected
(multiple selection callback). See the
DwtNsingleSelection attribute. For this
callback, the reason is DwtCRExtend.
DwtNextendConfirmCallback
Specifies the callback function or functions called
when the user double clicks MB 1 while depressing
the Shift key when more than one item is selected
(multiple selection callback). See the
DwtNsingleSelection attribute. For this
callback, the reason is DwtCRExtend.

5.10 List Box Convenience Functions
This section discusses the functions you· can use to:

5.10.1

•

Add and delete items to a list box widget

•
•

Delete an item by position
Deselect a single or all previously selected items

•

Verify the existence of an item

•

Select an item in the list box

•

Set the horizontal position

•

Make an item the first visible item in the list box

•

Make a position the top visible position in the list box

•

Select and deselect an item identified by its position in the list box

Adding and Deleting Items to a List Box Widget
The XUI Toolkit provides functions with which you can add or delete items
in a list box. To add an item to a list box, use DwtListBoxAddltem.

Dialog Box and Text Widget Functions 5-69

void DwtListBoxAddItern (widget, item, position)
Widget widget;
DwtCornpString item;
int position;

widget

Specifies the ID of the list box widget from whose list you
want to add an item.

item

Specifies the text of the item to be added to the list box.

position

Specifies the placement of the item within the list in terms of
its cell position. It uses an insert mode/cell number scheme
with a 1 specifying the topmost entry position and a 0
specifying the bottom entry for adding an item to the bottom
of the list.

The DwtListBoxAddItern function adds an item to a list within the list
box widget.
To delete an item from a list box, use DwtListBoxDeleteItern:
void DwtListBoxDeleteItern (widget, item)
Widget widget;
DwtCornpString item;

widget

Specifies the ID of the list box widget from whose list you
want to delete an item.

item

Specifies the text of the item to be deleted from the list box.

The DwtListBoxDeleteItern function deletes an item from a list within
the list box widget. The function searches the list for the item, removes it,
and moves any subsequent entries up one cell position throughout the
remaining list.

5.10.2

Deleting an Item By Position
To delete an item identified by its position from a list box, use
DwtListBoxDeletePos:
void DwtListBoxDeletePos (widget, position)
Widget widget;
int position;

widget

Specifies the ID of the list box widget from whose list you
want to delete an item identified by its position.

position

Specifies the position of the item to be deleted from the list.

The DwtListBoxDeletePos function deletes an item from a list within
the list box widget. The item to be deleted is identified by its position in the
list. The function searches the list for the specified position, removes the
5-70 Dialog Box and Text Widget Functions

item in that position, and moves any subsequent entries up one cell position
throughout the remaining list.

5.10.3

Deselecting a Single Item or All Previously Selected Items
To deselect a previously selected item in a list box, use
DwtListBoxDeselectItem:
void DwtListBoxDeselectItem (widget, item)
Widget widget;
DwtCompString item;

widget

Specifies the ID of the list box widget from whose list you
want to delete a single previously selected item.

item

Specifies the item in the list box to be deselected
(highlighting removed).

The DwtListBoxDeselectItem function deselects (removes
highlighting) an item previously selected, and removes it from the list of
selected items.
To deselect all the previously selected items in a list box, use
DwtListBoxDeselectAllItems:
void DwtListBoxDeselectAllItems (widget)
Widget widget;

widget

Specifies the ID of the list box widget from whose list you
want to delete all previously selected items.

The DwtListBoxDeselectAllItems function deselects (removes
highlighting) all items previously selected, and removes them from the list of
selected items.

5.10.4

Verifying the Existence of an Item
To verify the existence of a particular item in a list box, use
DwtListBoxItemExists:
int DwtListBoxItemExists (widget, item)
Widget widget;
DwtCompString item;

widget

Specifies the ID of the list box widget from whose list you
want to verify the existence of a specified item.

item

Specifies the item in the list box that is being searched for.

The DwtListBoxItemExists function searches through a list box to
determine if an item exists. If the specified item is found,

Dialog Box and Text Widget Functions 5-71

DwtListBoxIternExists returns an integer that gives the position of the
item in the list box. If the item is not found, DwtListBoxIternExists
returns a zero.

5.10.5

Selecting an Item in the List Box
To select an item in the list box, use DwtListBoxSelectItem.
void DwtLi stBoxSelect Item (widget, item, notify)
Widget widget;
DwtCompString item;
Boolean notify;

widget

Specifies the ill of the list box widget from whose list you
want to select an item.

item

Specifies the text of the item to be added to the list box.

notify

Specifies a boolean value that, when True, indicates use of
this widget results in a callback to the application.

The DwtListBoxSelectItem function selects an item in a list box, adds
it to a selected item list, and calls back to the application if notify is True.

5.10.6

Setting the Horizontal Position
To set the horizontal position to a specified position, use
DwtListBoxSetHorizPos:
void DwtListBoxSetHorizPos (widget, position)
Widget widget;
int position;

widget

Specifies the ID of the list box widget whose horizontal
scroll bar position you want to set.

position

Specifies the position of the horizontal scroll bar in the list
box widget.

The DwtListBoxSetHorizPos function is used only if the list box has
a horizontal scroll bar and the list box contains items too wide to be visible
within the current list box width.

5.10.7

Making an Item the First Visible Item in the List Box
To make a specified item the first visible item in a list box, use
DwtListBoxSetItem:

5-72 Dialog Box and Text Widget Functions

void DwtLi stBoxSet Item (widget, item)
Widget widget;
DwtCompString item;

widget

Specifies the widget ID.

item

Specifies the item to be made the first item in the list box.

The DwtListBoxSetItem function makes the specified item (if it exists)
the first visible item in a list box. The function determines which item in the
list box is displayed at the top of the list box, the choice of which is limited
by the DwtNi temsCount and DwtNvisibleItemsCount attributes to
the list box widget. When DwtNvisibleItemsCount is greater than 1
and less than DwtNi temsCount, the list box widget fills the list box with
the maximum visible items regardless of the position value.
For example, if DwtNitemsCount is 10 and
DwtNvisibleItemsCount is 5, you cannot make item 8 display at the
top of the list box. Instead, items 6 through 10 would be displayed. Setting
item to the fourth item in the list would make items 4 through 8 display. If
DwtNvisibleItemsCount is 1, you can make any item in the list be
displayed at the top of the list box.

5.10.8

Making a Position the Top Visible Position in the List Box
To make a specified position the top visible position in a list box, use
DwtListBoxSetPos:
void DwtLi stBoxSetPos (widget, position)
Widget widget;
int position;

widget

Specifies the ID of the list box widget whose specified item
number in the list you want displayed in the top position.

position

Specifies the item number in the list displayed in the top
position in the list box.

The DwtListBoxSetPos function makes the specified position (the item
number in the list) the top visible position in a list box. The function
determines which item in the list box is displayed at the top of the list box,
the choice of which is limited by the DwtNitemsCount and
DwtNvisibleItemsCount attributes to the list box widget. When
DwtNvisibleItemsCount is greater than 1 and less than
DwtNi temsCount, the list box widget fills the list box with the maximum
visible items regardless of the position value.
For example, if DwtNi terns Count is 10 and
DwtNvisibleIternsCount is 5, you cannot make item 8 be displayed at
the top of the list box. Instead, items 6 through 10 would be displayed.

Dialog Box and Text Widget Functions 5-73

Setting position to 4 would make items 4 through 8 be displayed. If
DwtNvisibleltemsCount is 1, you can make any item in the list be
displayed at the top of the list box.

5.10.9

Selecting and Deselecting an Item by Its Positiion in the
List Box
To select an item identified by its position in the list box, use
DwtListBoxSelectPos.
void DwtListBoxSelectPos (widget, position, notify)
Widget widget;
int position;
Boolean notify;

widget

Specifies the ID of the list box widget from whose list you
want to select an item.

position

Specifies an integer that identifies the position of the item to
be selected in the list box.

notify

Specifies a boolean value that, when True, indicates use of
this widget results in a callback to the application.

The DwtListBoxSelectPos function selects an item in a list box based
on its position in the list, adds it to a selected item list, and calls back to the
application, if notify is True.
To deselect an item identified by its position in the list box, use
DwtListBoxDeselectPos.
void DwtListBoxDeselectPos (widget, position)
Widget widget;
int position;

widget

Specifies the ID of the list box widget from whose list you
want to deselect an item.

position

Specifies an integer that identifies the position of the item to
be deselected in the list box.

The DwtListBoxDeselectPos function deselects an item (removes
highlighting) based on its position in a list box and removes the item from
the selected list.

5-74 Dialog Box and Text Widget Functions

Standard Menus and Dialog Box
Widget Functions

Many applications perform common tasks such as creating, modifying, or
editing files. To manage these common tasks, you will probably implement
standard menus and dialog boxes. The XVI Toolkit provides functions that
allow you to create instances of standard menus and standard dialog boxes.
This chapter discusses the functions you can use to:
•

Create a help menu widget

•

Create a work-in-progress box widget

•

Create a message box widget

•

Create a caution box widget

•

Create a command window widget

•

Manipulate the command line

•

Create a selection box widget

•

Create a file selection box widget

•

Initiate a search with a directory mask option

For guidelines on what to follow when implementing standard menus and
standard dialog boxes, see the XU] Style Guide.

6.1

Creating the Help Menu Widget
XVI application programmers are strongly encouraged to provide user
assistance as part of your applications. Applications that provide online
assistance to users should have a pull-down Help menu. For information on
invoking and designing the Help menu, see the XU] Style Guide.
To create an instance of the help menu widget, use DwtHelp or
DwtHelpCreate. When calling DwtHelp, you set the help menu widget
attributes presented in the formal parameter list. For DwtHelpCreate,
however, you specify a list of attribute name/value pairs that represent all the
possible help menu widget attributes. After you create an instance of this
widget, you can manipulate it using the appropriate X intrinsics functions. A
description of each follows:

Widget DwtHelp (parent_widget, name, de/aultyosition,

x, y, application_name,
library_type, library_spec, first_topic,
overview_topic, glossary_topic, unmap_callback)
Widget parent_widget;
DwtCompString name;
Boolean de/aultyosition;
Position x, y;
DwtCompString application_name;
int library_type;
DwtCompString library_spec;
DwtCompString first_topic;
DwtCompString overview_topic;
DwtCompString glossary topic;
DwtCallbackPtr unmap~allback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

de/aultyositionSpecifies a boolean value that, when True, indicates that
DwtNx and DwtNy will be ignored forcing the default. By
default the help widget is positioned so that it does not
occlude the parent widget on the screen. This argument sets
the DwtNde£aul tPosi tion attribute associated with
DwtHelpCreate.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left corner of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left corner of
the widget window relative to the inner upper left corner of
the parent window. This argument sets the DwtNy core
widget attribute.

application name
Specifies the application name to be used in the widget title
bar. This argument sets the DwtNapplicationName
attribute associated with DwtHelpCreate.
library_type

Specifies the type of help topic library specified by
DwtNlibrarySpec. You can pass DwtTextLibrary,
which is an ULTRIX help directory. This argument sets the
DwtNlibraryType attribute associated with
DwtHelpCreate.

library_spec

Specifies a host system file specification that identifies the
help topic library, for example, /usr /help/ decwhelp

6-2 Standard Menus and Dialog Box Widget Functions

on UNIX-based systems. This argument sets the
DwtNlibrarySpec attribute associated with
DwtHelpCreate.

Specifies the first help topic to be displayed. If you pass a
NULL string, the help menu widget displays a list of level
one topics. This argument sets the DwtNoverviewTopic
attribute associated with DwtHelpCreate.
overview_topic Specifies the application overview topic. This argument sets
the DwtNoverviewTopic attribute associated with
DwtHelpCreate.
glossary_topic Specifies the application glossary topic. If you pass a NULL
string, the Visit Glossary entry does not appear in the
widget's View pull-down menu. This argument sets the
DwtNglossaryTopic attribute associated with
DwtHelpCreate.
unmap callbackSpecifies the callback function or functions called when the
help menu widget window was unmapped. For this callback,
the reason is DwtCRUnmap. This argument sets the
DwtCRUnmap attribute associated with DwtHelpCreate.
Widget DwtHelpCreate (parent widget, name,
override argUst, override argcount)
Widget parent_widget;
char * name ;
ArgLi st override_arglist ;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_argUstSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override_ argUst).

The DwtHelp and DwtHelpCreate functions create an instance of a
help menu widget and return its associated widget ID.
The help menu widget is a modeless widget that allows the application to
display appropriate user assistance information in response to a user request.
The help menu widget displays an initial help topic and then gives the user
the ability to select and view additional help topics.
The DwtNfirstTopic attribute allows the application to provide
context-sensitive help by selecting a specific topic based on implicit or
explicit cues from the user.
Standard Menus and Dialog Box Widget Functions 6-3

The fonnat of the DwtNfirstTopic, DwtNoverviewTopic, and
DwtNglossaryTopic compound-strings depends on
DwtNlibraryType. If DwtNlibraryType is DwtTextLibrary,
the topic string is a sequence of help library keys separated by one or more
spaces.
Once the widget has been created, you can change the help topic by
specifying a new DwtNfirstTopic by calling XtSetValues, and then
causing the help menu widget to appear by calling XtManageChild.
When the user tenninates a help session (using the Exit function), the widget
is automatically unmanaged.
The following sections discuss these aspects of the help menu widget:

6.1.1

•

Callback infonnation

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRUnmap

The help window was unmapped.

6.1.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the help menu widget is:
•
•

core
composite

•
•

common
help

6-4 Standard Menus and Dialog Box Widget Functions

Based on this class hierarchy, the help menu widget inherits attributes from
the core, composite, and common widgets.
Table 6-1 lists the attributes inherited by the help menu widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 6-1: Attributes Inherited by the Help Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Determined by the geometry
manager
Cannot be set by the caller. The
help menu widget calculates the
width, based on the size of the
text window (DwtNcols and
DwtNrows).
Cannot be set by the caller. The
help menu widget calculates the
height, based on the size of the
text window (DwtNcols and
DwtNrows).
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Attribute Name
Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Standard Menus and Dialog Box Widget Functions 6-5

Table 6-1:

(continued)

Attribute Name

Data Type

Default

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

6.1.3

Widget-Specific Attributes
Table 6-2 lists the attributes inherited by the help menu widget.

Table 6-2: Widget-Specific Attributes for the Help Widget
Attribute Name

Data Type

Default

DwtNaboutLabel
DwtNaddtopicLabel
DwtNapplicationName
DwtNbadframeMessage
DwtNbadlibMessage
DwtNcacheHelpLibrary
DwtNcloseLabel
DwtNcols

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
Boolean
DwtCompString
int

DwtNcopyLabel
DwtNdefaultPosition
DwtNdismissLabel
DwtNeditLabel
DwtNerroropenMessage
DwtNexitLabel
DwtNfileLabel
DwtNfirstTopic
DwtNglossaryLabel
DwtNglossaryTopic
DwtNgobackLabel
DwtNgobacktopicLabel
DwtNgooverLabel
DwtNgotoLabel

DwtCompString
Boolean
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString

6-6 Standard Menus and Dialog Box Widget Functions

Table 6-2:

(continued)

Attribute Name

Data Type

Default

DwtNgototopicLabel
DwtNhelpAcknowledgeLabel
DwtNhelpFont

DwtCompString
DwtCompString
DwtFontList

DwtNhelpLabel
DwtNhelphelpLabel
DwtNhelpOnHelpTitle
DwtNhelpontitleLabel
DwtNhelptitleLabel
DwtNhistoryLabel
DwtNhistoryboxLabel
DwtNkeywordLabel
DwtNkeywordsLabel
DwtNlibrarySpec
DwtNlibraryType
DwtNnokeywordMessage
DwtNnotitleMessage
DwtNnulllibMessage
DwtNmapCallback
DwtNoverviewTopic
DwtNrows

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
int
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCompString
int

"Go To Topic"
"Acknowledge"
Language-dependent. The
American English default is " *-TERMINAL-MEDIUM-RNARROW--*-140*-*-C-*-IS08859-1"
"Using Help"
"Overview"
"Using Help"
"Help on"
"Help"
"History ... "
"Search Topic History"
"Keyword... "
"Keyword"

DwtNsaveasLabel
DwtNsearchapplyLabel
DwtNsearchkeywordboxLabel
DwtNsearchLabel
DwtNsearchtitleboxLabel
DwtNselectallLabel
DwtNtitleLabel
DwtNtitlesLabel
DwtNtopictitlesLabel
DwtNunmapCallback
DwtNviewLabel
DwtNvisitglosLabel
DwtNvisitLabel
DwtNvisittopicLabel

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCompString
DwtCompString
DwtCompString
DwtCompString

NULL
DwtTextLibrary
"Couldn't find keyword !CS"
"No title to match string !CS"
"No library specified\n"

NULL
NULL
Language-dependent. The
American English default is 20.
"Save As ... "
"Apply"
"Search Topic Keywords"
"Search"
"Search Topic Titles"
"Select All"
"Title... "
"Title"
"Topic Titles "

NULL
"View"
"Visit Glossary"
"Visit"
"Visit Topic"

Standard Menus and Dialog Box Widget Functions 6-7

DwtNaboutLabel

Specifies the text for one of the pull-down menu
entries displayed when the user clicks on the Help
entry on the menu bar.

DwtNaddtopicLabelSpecifies the text for the label indicating additional
topics for help.
DwtNapplicationName
Specifies the application name to be used in the
widget title bar.
DwtNbadframeMessage
Specifies the text for the message displayed when a
frame could not be found.
DwtNbadlibMessageSpecifies the text for the message displayed when a
requested library could not be found.
DwtNcacheHelpLibrary
Specifies a boolean value that, when True,
indicates that the text is stored in cache memory. If
Fa 1 s e, the text is not stored in cache memory.
DwtNcloseLabel

Specifies the label for the Exit push button in the
help widget window.

DwtNcols

Specifies the width, in characters, of the Help Menu
text window.

DwtNcopyLabel

Specifies the text for the copy entry on the pull-down
menu under Edit on the help widget menu bar.

DwtNdefaultPosition
Specifies a boolean value that, when True,
indicates that DwtNx and DwtNy will be ignored
forcing the default. By default the help widget is
positioned so that it does not occlude the parent
widget on the screen.
DwtNdismissLabel Specifies the text for the push button label used to
dismiss a help widget dialog box (for example,
Search History, Search Title, Search Keyword
boxes).
DwtNeditLabel

Specifies the text for the edit entry on the help
window menu bar.

DwtNerroropenMessage
Specifies the text for the error message displayed
when a file cannot be opened.
DwtNexitLabel
Specifies the text for the push button or pull-down
menu entry that allows the user to exit from help.

6-8 Standard Menus and Dialog Box Widget Functions

DwtNfileLabel

Specifies the text for the file entry on the help
window menu bar.

DwtNfirst Topic

Specifies the first help topic to be displayed. If you
pass a NULL string, the help menu widget displays a
list of level one topics.

DwtNglossaryLabelSpecifies the text for the glossary entry on the pulldown menu under Help on a help window menu bar.
DwtNglossaryTopicSpecifies the application glossary topic. If you pass
a NULL string, the Visit Glossary entry does not
appear in the widget's View pull-down menu.
DwtNgobackLabel Specifies the text for a label used on the pull-down
menu under View. Clicking on this object returns the
user to the previous topic displayed.
DwtNgobacktopicLabel
Specifies the label for the Go Back push button in
the help widget window.
DwtNgooverLabel Specifies the text for a label used on the pull-down
menu under View. Clicking on this label causes the
Overview of Help to appear in the Help window.
DwtNgotoLabel

Specifies the text for the label used on a push button
in the help widget's dialog boxes. Clicking on this
object after selecting a new topic displays help on the
new topic in the same Help window.

DwtNgototopicLabel
Specifies the label for the Go To Topic menu entry
in the View pull-down menu.
DwtNhelpAcknowledgeLabel
Specifies the label for the Acknowledge push button
in the error message box.
DwtNhelpFont
Specifies the font of the text displayed in the help
menu widget.
DwtNhelphelpLabelSpecifies the label for the Overview menu item in
the Using Help pull-down menu.
DwtNhelpLabel
Specifies the text for the label on the pull-down
menu under Help.
DwtNhelpOnHelpTitle
Specifies the label for the title bar in the Help-onHelp help widget.
DwtNhelpontitleLabel
Specifies the label for the help widget title bar used

Standard Menus and Dialog Box Widget Functions 6-9

in conjunction with the application name.

DwtNhelptitleLabel
Specifies the label for the help widget title bar when
no application name is specified.
DwtNhistoryLabel Specifies the text for the label in the pull-down menu
under Help.
DwtNhistoryboxLabel
Specifies the text for the label used in a history box.
DwtNkeywordLabel Specifies the text for the label in the pull-down menu
under Help.
DwtNkeywordsLabelSpecifies the text for the label used in a Search
Topic Keyword box to identify the text entry field.
DwtNlibrarySpec Specifies a host system file specification that
identifies the help topic library, for example,
/usr /help/ decwhelp on UNIX-based systems.
DwtNlibraryType Specifies the type of help topic library specified by
DwtNlibrarySpec. You can pass
DwtTextLibrary, which is an ULTRIX help
directory.
DwtNmapCallback Specifies the callback function or functions called
when the help widget is about to be mapped.
DwtNnokeywordMessage
Specifies the text for the message displayed when a
requested keyword cannot be found.
DwtNnotitleMessage
Specifies the text for the message displayed when a
requested title cannot be found.
DwtNnulllibMessage
Specifies the text for the message displayed when no
library has been specified.
DwtNoverviewTopicSpecifies the application overview topic.
DwtNrows

Specifies the height, in characters, of the Help Menu
text window.

DwtNsaveasLabel Specifies the text for an entry on a pull-down menu
under File on the Help menu bar. Clicking on this
entry allows a user to save the current help text in a
file. A file selection dialog box is displayed.
DwtNsearchapplyLabel
Specifies the text for the push button label used to

6-10 Standard Menus and Dialog Box Widget Functions

initiate a search action in a Search dialog box.
DwtNsearchkeywordboxLabel
Specifies the text for the label used in a Search Topic
Keywords box.
DwtNsearchLabel Specifies the text for an entry on a Help window
menu bar.
DwtNsearchtitleboxLabel
Specifies the text for the title of a Search Topic
Titles box.
DwtNselectallLabel
Specifies the text for an entry on the pull-down menu
under Edit. Clicking on this entry selects all the text
in the work area (text widget only).
DwtNtitleLabel

Specifies the text for an entry on the pull-down menu
under Search. Clicking on this entry allows a user to
search for a topic by title.

DwtNti tlesLabel Specifies the text for the label that identifies the text
entry field on the Search Topic Titles box.
DwtNtopictitlesLabel
Specifies the text for the label that identifies the
topics found as a result of a title search in a Search
Topic Titles box.
DwtNviewLabel

Specifies the text for the View entry on a help menu
bar.

DwtNvisitglosLabel
Specifies the text for the pull-down menu entry under
View. Clicking on this entry causes the glossary to
be displayed in a new Help window.
DwtNvisi tLabel

Specifies the text for an entry on a push button in a
help widget's dialog boxes. Clicking on this object
causes information on a new topic to be displayed in
a new window.

DwtNvisittopicLabel
Specifies the label for the Visit Topic menu entry in
the View pull-down menu.
DwtNunmapCallbackSpecifies the callback function or functions called
when the help menu widget window was unmapped.
For this callback, the reason is DwtCRUnmap.

Standard Menus and Dialog Box Widget Functions 6-11

6.2 Creating the Work-in-Progress Box Widget
Your application can indicate that a time-consuming operation is taking place
by using a standard dialog box called the work-in-progress box. To create an
instance of the work-in-progress box widget, use DwtWorkBox or
DwtWorkBoxCreate. When calling DwtWorkBox, you set the work-inprogress box widget attributes presented in the formal parameter list. For
DwtWorkBoxCreate, however, you specify a list of attribute name/value
pairs that represent all the possible work-in-progress box widget attributes.
Mter you create an instance of this widget, you can manipulate it using the
appropriate X intrinsics functions. A description of each follows:
Widget DwtWorkBox (parent_widget, name, defaultyosition,

x, y, style, label, cancel label,
callback, help callback) Widget parent_widget;
char *name;
Boolean defaultyosition;
Position x, y;
int style;
DwtCompString label, cancel label;
DwtCallbackPtr callback, hetp_callback;
parent_widget Specifies the parent widget ID.
name
Specifies the name of the created widget.
defaultyositionSpecifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. If False, the specified DwtNx and
DwtNy attributes are used to position the widget. This
argument sets the DwtNdefaul tPosi tion attribute
associated with DwtDialogBoxCreate.
x

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

style

Specifies the style of the dialog box widget. You can pass
DwtModal (modal) or DwtModeless (modeless). This
argument sets the DwtNstyle attribute associated with
DwtDialogBoxPopupCreate.

6-12 Standard Menus and Dialog Box Widget Functions

Specifies the text in the message line or lines. This argument
sets the DwtNlabel attribute associated with

label

DwtWorkBoxCreate.

cancel label

Specifies the label for the Cancel push button. If the label is
a NULL string, the button is not displayed. This argument
sets the DwtNcancelLabel attribute associated with
DwtWorkBoxCreate.

callback

Specifies the callback function or functions called back when
the Cancel button is activated. This argument sets the
DwtNcancelCallback attribute associated with
DwtWorkBoxCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtWorkBoxCreate (parent_widget, name,

override_argUst, override_ argcount)
Widget parent_widget;
char *name;
ArgList override_argUst;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _argUst).
The DwtWorkBox and DwtWorkBoxCreate functions create an instance
of a work-in-progress box widget and return its associated widget ID. The
work-in-progress box widget is a dialog box that allows the application to
display work in progress messages to the user. When the application
determines that an operation will take longer than five seconds, it is
recommended that the application call this function to display a work-inprogress box with a message such as "Work in Progress.lPlease Wait."
The work-in-progress box may contain a push button labeled "Cancel
Operation. ' , Do not include the push button if the operation cannot be
canceled. If the style is DwtModal when the user selects the Cancel push
button, the widget is cleared from the screen, but not destroyed. The widget
can be redisplayed by calling XtManageChild.
The work-in-progress box widget follows the same rules for geometry
management and resizing as its superclass the dialog pop-up widget. For

Standard Menus and Dialog Box Widget Functions 6-13

information on geometry management, see Section 5.1.2; for information on
resizing, see Section 5.1.3.
The following sections discuss these aspects of the work-in-progress box
widget:

6.2.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRCancel

The user activated the cancel push button.

DwtCRFocus

The work-in-progress box has received the
input focus.

DwtCRHelpRequested

The user selected Help somewhere in the
work-in-progress box.

6.2.2 Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the work-in-progress box is:

•

core

•

composite

•
•

constraint

•

message

dialog

6-14 Standard Menus and Dialog Box Widget Functions

Based on this class hierarchy, the work-in-progress box widget inherits
attributes from the core, composite, constraint, and dialog box widgets. Note
that the work-in-progress box is a message class widget. Note also that you
cannot set the attributes for the composite or constraint widgets; therefore,
they are not shown.
Table 6-3 lists the attributes inherited by the work-in-progress box widget.
For descriptions of the core attributes, see Chapter 1. For descriptions of the
dialog widget attributes, see Section 5.1.5.

Table 6-3: Attributes Inherited by the Work-in-Progress Box
Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Dialog Pop.Up Attributes
DwtNforeground
DwtNhighlight

Pixel
Pixel

Default foreground color
Default foreground color

Standard Menus and Dialog Box Widget Functions 6-15

Table 6-3:

6.2.3

(continued)

Attribute Name

Data Type

Default

DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNtitle
DwtNstyle
DwtNmapCallback
DwtNunmapCallback
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNtakeFocus

Pixmap
Opaque *
DwtFontList
DwtCallbackptr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char
DwtCallbackptr
DwtCallbackptr
DwtCallbackptr
NOT SUPPORTED
Dimension
Dimension
Boolean
NOT SUPPORTED
unsigned char
Boolean

NULL
NULL

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
NOT SUPPORTED
NOT SUPPORTED

The default XUI Toolkit font

NULL
Widget name
DwtModal

NULL
NULL
NULL
12 pixels
10 pixels
False
DwtResizeShrinkWrap
True for modal dialog box
False for modeless dialog box
True (that is, no window
manager resize button)
True

Widget Class Hierarchy and Inherited Attributes
Table 6-4 lists the widget-specific attributes for the work-in-progress box
widget. Descriptions of these attributes follow the table.

Table 6-4: Widget-Specific Attributes for the Work-in-Progress
Box Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNcancelLabel
DwtNcancelCallback

DwtCompString
DwtCompString
DwtCallbackPtr

Widget name
"Cancel"

6-16 Standard Menus and Dialog Box Widget Functions

NULL

Table 6-4:
DwtNlabel

(continued)
Specifies the text in the message line or lines.

DwtNcancelLabel Specifies the label for the Cancel push button. If the
label is a NULL string, the button is not displayed.
DwtNcancelCallback
Specifies the callback function or functions called
when the user clicks on the Cancel button. For this
callback, the reason is DwtCRCancel.

6.3 Creating a Message Box Widget
Your application should generate a message box when the user does
something unexpected, or when your application needs to display an
infonnational message to the user. A message box can freeze your
application and require the user to explicitly dismiss the message box before
the application may proceed.
To create an instance of the message box widget, use DwtMe s s ageBox or
DwtMessageBoxCreate. When calling DwtMessageBox, you set the
message box attributes presented in the fonnal parameter list. For
DwtMessageBoxCreate, however, you specify a list of attribute
name/value pairs that represent all the possible message box widget
attributes. After you create an instance of this widget, you can manipulate it
using the appropriate X intrinsics functions. A description of each follows:
Widget DwtMessageBox (parent_widget, name, de/aultyosition,

x, y, style, ok label, label,
callback, help callback)
Widget parent widget;
char * name ;
Boolean de/aultyosition;
Position x, y;
int style;
DwtCompString ok label, label;
DwtCallbackPtr callback;
DwtCallbackPtr help_callback;
parent_widget Specifies the parent widget ID.
name
Specifies the name of the created widget.
de/aultyositionSpecifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. If False, the specified DwtNx and
DwtNy attributes are used to position the widget. This

Standard Menus and Dialog Box Widget Functions 6-17

argument sets the DwtNdefaul tPosi tion attribute
associated with DwtDialogBoxCreate.
x

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

style

Specifies the style of the dialog box widget. You can pass
DwtModal (modal) or DwtModeless (modeless). This
argument sets the DwtNstyle attribute associated with
DwtDialogBoxPopupCreate.

label

Specifies the text in the message line or lines. This argument
sets the DwtNlabel attribute associated with
DwtMessageBoxCreate.

ok label

Specifies the label for the Ok push button. If the label is a
NULL string, the button is not displayed. This argument sets
the DwtNokLabel attribute associated with
DwtMessageBoxCreate.

callback

Specifies the callback function or functions called when the
user activates the OK push button. This argument sets the
DwtNyesCallback attribute associated with
DwtMessageBoxCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtMessageBoxCreate (parent_widget, name,
override arglist,
override argcount)
Widget parent_widget;
char * name ;
ArgLi st override arglist;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
6-18 Standard Menus and Dialog Box Widget Functions

argument list (override_ arglist).
The DwtMessageBox and DwtMessageBoxCreate functions create an
instance of the message box widget and return its associated widget ill. The
DwtMessageBoxCreate function conforms to the XUI Style Guide by
providing optional secondary text below the primary text. This function also
supports alignment mode for both the DwtNlabelAlignrnent and
DwtN s e condLabe lAl i gnrnent attributes.
The message box widget is a dialog box that allows the application to display
informational messages to the user. You call this function to create a
message box when the user does something unexpected, or when your
application needs to display information to the user. The message box
widget may contain an OK push button. When the style is DwtModal, the
message box freezes the application and requires the user to explicitly
dismiss the message box before the application proceeds. If the style is
DwtModal when the user selects the OK push button, the widget is cleared
from the screen but not destroyed. You can redisplay the widget by calling
XtManageChild.

The message box widget follows the same rules for geometry management as
its superclass the dialog box widget. See the DwtDialogBoxCreate
function for more information.
The message box widget follows the same rules for resizing as its superclass
the dialog box widget. See the DwtDialogBoxCreate function for more
information. The following sections discuss these aspects of the message
box widget:

6.3.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStructi

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRYes

The user activated the Yes button.

Standard Menus and Dialog Box Widget Functions 6-19

DwtCRFocus

The message box has received the input
focus.

DwtCRHelpRequested

The user selected Help somewhere in the
message box.

6.3.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the message box widget is:

•
•
•

core

•
•

dialog

composite
constraint
message

Based on this class hierarchy, the message box widget inherits attributes from
the core, composite, constraint, and dialog box widgets. Note that the
message box is a message class widget. Note also that you cannot set the
attributes for the composite or constraint widgets; therefore, they are not
shown.
Table 6-5 lists the attributes inherited by the message box widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 6-5: Attributes Inherited by the Message Box Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth

Dimension
Dimension
Dimension

Determined by the geometry
manager
Determined by the geometry
manager
5 pixels
5 pixels
One pixel

Core Attributes

6-20 Standard Menus and Dialog Box Widget Functions

Table 6-5:

(continued)

Attribute Name

Data Type

DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Default
Default foreground color

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Dialog Pop-Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNtitle
DwtNstyle
DwtNmapCallback
DwtNunmapCallback
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNtakeFocus

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
NOT SUPPORTED
Dimension
Dimension
Boolean
NOT SUPPORTED
unsigned char
Boolean

Default foreground color
Default foreground color

NULL
NULL
The default XUI Toolkit font

NULL
Widget name
DwtModal

NULL
NULL
NULL
12 pixels
10 pixels
False

DwtResizeShrinkWrap
True for modal dialog box
False for modeless dialog box

Standard Menus and Dialog Box Widget Functions 6-21

Table 6-5:

(continued)

Attribute Name

Data Type

Default

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
NOT SUPPORTED
NOT SUPPORTED

True (that is, no window
manager resize button)
True

6.3.3 Widget-Specific Attributes
Table 6-6 lists the widget-specific attributes for the message box widget.
Descriptions of these attributes follow the table.

Table 6-6: Widget-Specific Attributes for the Message Box
Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNokLabel
DwtNyesCallback
DwtNsecondLabel
DwtNlabelAlignment
DwtNsecondLabelAlignment
DwtNiconPixmap

DwtCompstring
DwtCompString .
DwtCallbackPtr
DwtCompString
unsigned char
unsigned char
Pixmap

Widget name
"Acknowledged"
NULL
NULL
DwtAlignmentCenter
DwtAlignmentBeginning
The default is the standard icon
provided for each message-class
widget as follows: (1) the default
caution box icon is an
exclamation point; (2) the default
message bo~ icon is an asterisk;
(3) the default work box icon is
the wait cursor (watch). See the
XUI Style Guide for illustrations
of the icons for each message
class widget.

DwtNlabel

Specifies the text in the message line or lines.

DwtNokLabel

Specifies the label for the Ok push button. If the
label is a NULL string, the button is not displayed.

DwtNyesCallback Specifies the callback function or functions called
when the user clicks on the Yes button. For this

6-22 Standard Menus and Dialog Box Widget Functions

callback, the reason is DwtCRYes.
DwtNsecondLabel Specifies the text for the secondary label. If the

application specifies a second label and then wants to
remove it, it should use XtSetValues to set
DwtNsecondLabel to NULL or to an empty
compound-string.
DwtNlabelAlignment

Specifies the alignment for the primary label. You
can pass DwtAlignmentCenter (center
alignment), DwtAlignmentBeginning
(alignment at the beginning), or
DwtAlignmentEnd (alignment at the end).
DwtNsecondLabelAlignment

Specifies the alignment for the secondary label. You
can pass DwtAlignmentCenter (center
alignment), DwtAlignmentBeginning
(alignment at the beginning), or
DwtAlignmentEnd (alignment at the end).
DwtNiconPixmap

Specifies the pixmap used for the icon.

6.4 Creating a Caution Box Widget
A caution box warns the user of the consequences of carrying out an action.
It stops application activity and requires the user to provide instructions on
how to proceed. The box may contain Yes, No, and Cancel push buttons.
To create an instance of the caution box widget, use DwtCautionBox or
DwtCautionBoxCreate. When calling DwtCautionBox, you set the
caution box widget attributes presented in the formal parameter list. For
DwtCautionBoxCreate, however, you specify a list of attribute
name/value pairs that represent all the possible caution box widget attributes.
Mter you create an instance of this widget, you can manipUlate it using the
appropriate X intrinsics functions. A description of each follows:
Widget DwtCautionBox (parent_widget, name, defaultyosition,

x, y, style, label,
yeslabel, nolabel, cancel label,
defaultyush_button, callback,
help_callback)
Widget parent_widget;
char * name ;
Boolean defaultyosition;
Position x, y;
int style;

Standard Menus and Dialog Box Widget Functions 6-23

DwtCornpString label;
DwtCornpString yeslabel;
DwtCornpString nolabel;
Dwt CornpSt ring cancel label;
int defaultyush_button ;DwtCallbackPtr callback, help_callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

defaultyositionSpecifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. H False, the specified DwtNx and
DwtNy attributes are used to position the widget. This
argument sets the DwtNdefaul tPosi tion attribute
associated with DwtDialogBoxCreate.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

style

Specifies the style of the caution box widget. You can pass
DwtModal (modal) or DwtModeless (modeless). This
argument sets the DwtNstyle attribute associated with
DwtDialogBoxPopupCreate.

label

Specifies the text in the message line or lines. This argument
sets the DwtNlabel attribute associated with
DwtCautionBoxCreate.

yeslabel

Specifies the label for the Yes push button. If the label is a
zero length string, the button is not displayed. This
argument sets the DwtNyesLabel attribute associated with
DwtCautionBoxCreate.

nolabel

Specifies the label for the No push button. If the label is a
zero length string, the button is not displayed. This
argument sets the DwtNnoLabel attribute associated with
DwtCautionBoxCreate.

cancel label

Specifies the label for the Cancel push button. If the label is
a NULL string, the button is not displayed. This argument
sets the DwtNcancelLabel attribute associated with
DwtCautionBoxCreate.

6-24 Standard Menus and Dialog Box Widget Functions

defaultyush_button
Specifies the push button that represents the default user
action. You can pass DwtYesButton, DwtNoButton,
or DwtCancelButton. This argument sets the
DwtNdefaultPushbutton attribute associated with
DwtCautionBoxCreate.
callback

Specifies the callback function or functions called when the
user activates the Yes, No, or Cancel buttons. This argument
sets the DwtNyesCallback, DwtNnoCallback, and
DwtNcancelCallback attributes associated with
DwtCautionBoxCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtCautionBoxCreate (parent_widget, name,
override_arglist,
override_argcount)
Widget parent_widget;
char *name;
ArgLi st override_arglist ;
in t override_argcount i

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _arglist).
The DwtCautionBox and DwtCautionBoxCreate functions create a
caution box widget and return its associated widget !D. A caution box warns
the user of the consequences of carrying out an action. It stops application
activity and requires the user to provide instructions on how to proceed. The
box may contain Yes, No, and Cancel push buttons. If DwtNstyle is
DwtModal when the user activates any push button, the widget is cleared
from the screen, but not destroyed. You can redisplay the widget by calling
XtManageChi Id.
The caution box widget follows the same rules for geometry management as
its superclass the dialog box widget. See DwtDialogBoxCreate for
more information.

Standard Menus and Dialog Box Widget Functions 6-25

The caution box widget follows the same rules for resizing as its superclass
the dialog box widget. See DwtDialogBoxCreate for more information.
The following sections discuss these aspects of the main window widget:

6.4.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRYes

The user activated the Yes button.

DwtCRNo

The user activated the No button.

DwtCRCancel

The user activated the Cancel button.

DwtCRFocus

The caution box has received the input
focus.

DwtCRHelpRequested

The user selected Help somewhere in the
caution box.

6.4.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the caution box widget is:
•
•

core
composite

6-26 Standard Menus and Dialog Box Widget Functions

•

constraint

•

dialog

•

message

Based on this class hierarchy, the caution box widget inherits attributes from
the core, composite, constraint, and dialog box widgets. Note that the
caution box is a message class widget. Note also that you cannot set the
attributes for the composite or constraint widgets; therefore, they are not
shown.
Table 6-7 lists the attributes inherited by the caution box widget. For
descriptions of the core and common attributes, see Chapter 1.
Table 6-7: Attributes Inherited by the Caution Box Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Depth of the parent window
NULL
True
The parent screen

Pixel

Default foreground color

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL

Dialog Pop-Up Attributes
DwtNforeground

Standard Menus and Dialog Box Widget Functions 6-27

Table 6-7:

6.4.3

(continued)

Attribute Name

Data Type

Default

DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNtitle
DwtNstyle
DwtNmapCallback
DwtNunmapCallback
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNtakeFocus

Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackptr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char
DwtCallbackptr
DwtCallbackptr
DwtCallbackPtr
NOT SUPPORTED
Dimension
Dimension
Boolean
NOT SUPPORTED
unsigned char
Boolean

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
NOT SUPPORTED
NOT SUPPORTED

Default foreground color

NULL
NULL
The default XUI Toolkit font

NULL
Widget name
DwtModal

NULL
NULL
NULL
12 pixels
10 pixels
False
DwtResizeShrinkWrap
True for modal dialog box
False for modeless dialog box
True (that is, no window
manager resize button)
True

Widget-Specific Attributes
Table 6-8 lists the widget-specific attributes for the caution box widget.
Descriptions of these attributes follow the table.

Table 6-8: Widget-Specific Attributes for the Caution Box Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNyesLabel
DwtNnoLabel
DwtNcancelLabel

DwtCompString
DwtCompString
DwtCompString
DwtCompString

Widget name
"Yes"
"No"
"Cancel"

6-28 Standard Menus and Dialog Box Widget Functions

Table 6-8:

(continued)

Attribute Name

Data Type

Default

DwtNdefaultPushbutton
DwtNyesCallback
DwtNnoCallback
DwtNcancelCallback

unsigned char

DwtYesButton

DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr

NULL
NULL

NULL

DwtNlabel

Specifies the text in the message line or lines.

DwtNyesLabel

Specifies the label for the Yes push button. If the
label is a zero length string, the button is not
displayed.

DwtNnoLabel

Specifies the label for the No push button. If the
label is a zero length string, the button is not
displayed.

DwtNcancelLabel Specifies the label for the Cancel push button. If the
label is a NULL string, the button is not displayed.
DwtNdefaultPushbutton
Specifies the push button that represents the default
user action. You can pass DwtYesButton,
DwtNoButton, or DwtCancelButton.
DwtNyesCallback Specifies the callback function or functions called
when the user clicks on the Yes button. For this
callback, the reason is Dwt CRYe s.
DwtNnoCallback

Specifies the callback function or functions called
when the user clicks on the No button. For this
callback, the reason is DwtCRNo.

DwtNcancelCallback
Specifies the callback function or functions called
when the user clicks on the Cancel button. For this
callback, the reason is DwtCRCancel.

6.5 Creating the Command Window
A command window allows the user to enter commands from the keyboard
rather than using the mouse.
To create an instance of the command window widget, use
DwtCommandWindowor DwtCommandWindowCreate. When calling
DwtCommandWindow, you set the command window widget attributes
presented in the formal parameter list. For DwtCommandWindowCreate,

Standard Menus and Dialog Box Widget Functions 6-29

however, you specify a list of attribute name/value pairs that represent all the
possible command window widget attributes. Mter you create an instance of
this widget, you can manipulate it using the appropriate X intrinsics
functions. A description of each follows:
Widget DwtCommandWindow (parent_widget, name, prompt,

lines, callback, help_callback)
Widget parent_widget;
char * name;
DwtCompString prompt;
int lines;
DwtCallbackPtr callback, help_callback;

parent_widget Specifies the parent widget ID.
name
Specifies the name of the created widget.
prompt

Specifies the command line prompt. This argument sets the
DwtNprompt attribute associated with
DwtCommandWindowCreate.

lines

Specifies the number of command history lines visible in the
command window widget. This argument sets the
DwtNlines attribute associated with
DwtCommandWindowCreate.

callback

Specifies the callback function or functions called when the
user enters a command or changes the contents of a
command line. This argument sets the
DwtNcommandEnteredCallback and
DwtNval ueChangedCallback attributes associated with
DwtCommandWindowCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtCommandWindowCreate (parent_widget, name,

override_arglist ,
override_argcount)
Widget parent_widget;
char * name;
ArgList override_arglist;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

6-30 Standard Menus and Dialog Box Widget Functions

6.5.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
int length;
char *value;
DwtCommandWindowCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRCommandEntered

The user terminated the command line with
a carriage return/line feed.

DwtCRValueChanged

The contents of the command line have
changed.

DwtCRFocus

The command window widget has received
the input focus.

DwtCRHelpRequested

The user selected Help.

Standard Menus and Dialog Box Widget Functtons 6-31

6.5.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the command window widget is:

•
•
•
•
•

core
composite
constraint
dialog
command

Based on this class hierarchy, the command window widget inherits attributes
from the core, composite, constraint, and dialog box widgets. Note that you
cannot set the attributes for the composite or constraint widgets; therefore,
they are not shown.
Table 6-9 lists the attributes inherited by the command window widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 6-9: Attributes Inherited by the Command Window Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
zero
zero
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True

Core Attributes

6-32 Standard Menus and Dialog Box Widget Functions

Table 6·9:

(continued)

Attribute Name

Data Type

Default

DwtNancestorSensitive

Boolean

The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackptr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char
DwtCallbackptr
DwtCallbackptr
DwtCallbackPtr
NOT SUPPORTED
Dimension
Dimension
Boolean

DwtNchildOverlap
DwtNresize
DwtNtakeFocus

NOT SUPPORTED
NOT SUPPORTED
Boolean

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton

Boolean
NOT SUPPORTED

Default foreground color
Default foreground color

NULL
NULL
The default XVI Toolkit font

NULL
Widget name
DwtModal

NULL
NULL
NULL
12 pixels
10 pixels
True
This causes the command window
to be positioned in the bottom
left-hand comer of the parent
widget.

True for modal dialog box
Fa 1 s e for modeless dialog box
True (that is, no window
manager resize button)
True

Standard Menus and Dialog Box Widget Funct~ons 6-33

Table 6-9:

6.5.3

(continued)

Attribute Name

Data Type

Default

DwtNcancelButton
DwtNcancelButton

Widget

NULL

NOT SUPPORTED

Widget-Specific Attributes
Table 6-10 lists the widget-specific attributes for the command window
widget. Descriptions of these attributes follow the table.

Table 6-10: Widget-Specific Attributes for the Command Window
Widget
Attribute Name

Data Type

Default

DwtNvalue
DwtNprompt
DwtNlines
DwtNhistory
DwtNcommandEnteredCallback
DwtNvalueChangedCallback
DwtNtTranslation

char *
DwtCompString
short
char *
DwtCallbackPtr
DwtCallbackptr
XtTranslations

NULL
">"
Two lines

NULL
NULL
NULL

DwtNvalue

Specifies the current contents of the command line
string. When a command-entered callback is made,
this attribute will be the command line that just
executed.

DwtNprompt

Specifies the command line prompt.

DwtNlines

Specifies the number of command history lines
visible in the command window widget.

DwtNhistory

Specifies the contents of the command line history.
Multiple lines should be separated by a linefeed
character (<LF».

DwtNcommandEnteredCallback
Specifies the callback function or functions called
when the user terminated the command line with a
carriage return/line feed. For this callback, the
reason is DwtCRCommandEntered.

6-34 Standard Menus and Dialog Box Widget Functions

DwtNvalueChangedCallback

Specifies the callback function or functions called
when the contents of the command line have
changed. For this callback, the reason is
DwtCRValueChanged.
DwtNt Translation Specifies the translations used for the command line

text field.

6.6 Manipulating the Command Line
The XUI Toolkit provides functions with which you can manipulate the
command line. This section discusses how to:
•

Append a string to the command line

•

Write an error message in the history area

•

Replace the current command string

To append a passed string to the current command line, use
DwtCommandAppend.
void DwtCommandAppend (widget, command)
Widget widget;
char * command;

widget

Specifies the ID of the command window widget to whose
command line you want to append the passed string.

command

Specifies the text to be appended to the command line. This
argument is a NULL-terminated string.

The DwtCommandAppend function appends the passed string to the
current command line, within the command window widget. If the string
sent is terminated with a carriage return «CR» or carriage return and/or
linefeed «CR><LF» character, then the command is executed, the
application is informed, the command is moved to the command history, and
a new prompt is issued.
To write an error message in the command window, use
DwtCommandErrorMessage.
void DwtCornmandErrorMessage (widget, error)
Widget widget;
char * error;

widget

Specifies the ID of the command window widget in whose
command window you want to write an error message.

Standard Menus and Dialog Box Widget Functions 6-35

error

Specifies the error message to be placed in the bottom-most
history line in the command window widget. This argument
is a NULL-terminated string.

The DwtCommandErrorMessage function writes an error message in the
history area within the command window widget. The history is first
scrolled up.
To replace the current command string with the one passed, use
DwtCommandSet.
void DwtCommandSet (widget, command)
Widget widget;
char * command;

widget

Specifies the ID of the command window widget whose
current command string you want to replace.

command

Specifies the text to replace the text currently on the
command line. This argument is a NULL-terminated string.

The DwtCommandSet function replaces the current command string with
the passed string within the command window widget. A zero length string
is used to clear the current command line. If the string is terminated by a
carriage return «CR», linefeed «LF», or carriage return and/or linefeed
«CRxLF», then the command is executed, the application is informed, the
command is moved to the command history, and a new prompt is issued.

6.7 Creating a Selection Box Widget
To create an instance of the selection box widget, use DwtSelection or
DwtSelectionCreate. When calling DwtSelection, you set the
selection box widget attributes presented in the formal parameter list. For
DwtSelectionCreate, however, you specify a list of attribute
name/value pairs that represent all the possible selection box widget
attributes. After you create an instance of this widget, you can manipulate it
using the appropriate X intrinsics functions. A description of each follows:
Widget DwtSelection (parent_widget, name, x, y,

title, value, items,
item_count, visible_items_count, style,
defaultyosition, callback, help_callback)
Widget parent_widget;
char *name;
Position x, y;
DwtCornpString title;
DwtCornpString value;
DwtCornpString * items;

6-36 Standard Menus and Dialog Box Widget Functions

int item_count, visible_items_count;
int style;
Boolean dejaultyosition;
DwtCallbackPtr callback, help_callback;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget. attribute.

title

SpeCifies the text that appears in the banner of the selection
box. This argument sets the DwtNtitle attribute
associated with DwtDialogBoxCreate.

value

Specifies the text in the text edit field. This argument sets
the DwtNval ue attribute associated with
DwtSelectionCreate.

items

Specifies the items in the selection widget's list box. This
argument sets the DwtNi terns attribute associated with
DwtSelectionCreate.

item count

Specifies the number of items in the selection widget'S list
box. This argument sets the DwtNi terns Count associated
with DwtSelectionCreate.

visible items count
- Specifies the number of items displayed in the selection
widget's list box. This argument sets the
DwtNvisiblelternsCount attribute associated with
DwtSelectionCreate.

style

Specifies the style of the pop-up dialog box widget. You can
pass DwtModal (modal) or DwtModeless (modeless).
This argument sets the DwtNstyle attribute associated
with DwtDialogBoxPopupCreate.

dejaultyositionSpecifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. If False, the specified DwtNx and

Standard Menus and Dialog Box Widget Functions 6-37

DwtNy attributes are used to position the widget. This
argument sets the DwtNdefaultPosition attribute
associated with DwtDialogBoxCreate.

callback

Specifies the callback function or functions called when the
user makes or cancels a selection, or there is no match for the
item selected by the user. This argument sets the
DwtNactivateCallback, DwtNcancelCallback,
and DwtNnoMatchCallback attributes associated with
DwtSelectionCreate.

help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtSelectionCreate (parent_widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char * name ;
ArgLi st override arglist;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _argUst).
The DwtSelection and DwtSelectionCreate functions create an
instance of a selection box widget and return its associated widget ID. The
selection widget is a pop-up dialog box containing a label widget, a text
entry widget holding the current value, a list box displaying the current item
list, and Ok and Cancel push buttons.
When realized, the selection widget displays the item list passed by the
caller. The current value is displayed in the text entry field. Users make
selections by clicking the mouse in the list box or by typing item names in
the text entry field. The selection widget does not do file searches. To
perform file searches, use DwtFileSelectionCreate.
The selection widget follows the same rules for geometry management and
resizing as its superc1ass the dialog box widget. However, the selection
widget allows only one child, and it places the child between the list box and
the push buttons. The child cannot be a gadget.
See DwtDialogBoxCreate for more information.

6-38 Standard Menus and Dialog Box Widget Functions

The following sections discuss these aspects of the selection box widget:

6.7.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
DwtCompString value;
int value len;
DwtSelectionCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActi vate

The user activated the Ok push button or
double clicked on an item that has an exact
match in the list box.

DwtCRNoMatch

The user activated the Ok push button or
double clicked on an item that does not
have an exact match in the list box.

DwtCRCancel

The user activated the Cancel button.

DwtCRHelpRequested

The user selected help somewhere in the
file selection box.

6.7.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the selection box widget is:
•

core

Standard Menus and Dialog Box Widget Functions 6-39

•

composite

•

constraint

•
•

dialog
selection

Based on this class hierarchy, the selection widget inherits attributes from the
core, composite, constraint, and dialog box widgets. Note that you cannot set
the attributes for the composite or constraint widgets; therefore, they are not
shown.
Table 6-11 lists the attributes inherited by the selection box widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 6-11: Attributes Inherited by the Selection Box Widget
Attribute Name

Data Type

Default

DwtNx
DwtNy
DwtNwidth

Position
Position
Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Centered in the parent window
Centered in the parent window
The width of the list box, plus tl
width of the push buttons, plus
three times
DwtNmarginWidth. The list
box will grow to accommodate
items wider than the title.
The height of the list box, plus
the height of the text edit field,
plus the height of the label, plus
three times
DwtNmarginHeight.
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged

XtTranslations
int
XtTranslations
Boolean

Core Attributes

6-40 Standard Menus and Dialog Box Widget Functions

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive ane
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True

Table 6·11:

(continued)

Attribute Name

Data Type

Default

DwtNscreen
DwtNdestroyCallback

Screen *
DwtCallbackptr

The parent screen
NULL

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNstyle
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNnoResize

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackptr
unsigned char
unsigned char
unsigned char
DwtCallbackptr
XtTranslations
Dimension
Dimension
Boolean
Boolean
unsigned char
Boolean

DwtNtitle
DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

DwtCompString
DwtCallbackPtr
DwtCallbackPtr
Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
Widget
Widget

Default foreground color
Default foreground color
NULL
NULL
The default XUI Toolkit font
NULL
DwtDirectionRightDown
DwtFontUnits
DwtModal
NULL
NULL
5 pixels
5 pixels
False
True
DwtResizeGrowOnly
True (that is, no window
manager resize button)
"Open"
NULL
NULL
True for modal dialog box
Fa 1 s e for modeless dialog box
True
NULL
NULL

Dialog Pop-Up Attributes

6.7.3

Widget-Specific Attributes
Table 6-12 lists the widget-specific attributes for the selection box widget.
Descriptions of these attributes follow the table.

Standard Menus and Dialog Box Widget Functions 6-41

Table 6-12: Widget-Specific Attributes for the Selection Box
Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNvalue
DwtNokLabel
DwtNcancelLabel
DwtNactivateCallback
DwtNcancelCallback
DwtNnoMatchCallback
DwtNvisibleltemsCount
DwtNitems
DwtNitemsCount
DwtNmustMatch
DwtNselectionLabel

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
int
DwtCompString *
int
Boolean
DwtCompString

"Items"

DwtNlabel

"Ok"
"Cancel"
NULL
NULL
NULL
8
NULL
Zero
False
"Selection"

Specifies the label to appear above the list box
containing the items.

Specifies the text in the text edit field.
DwtNselectionLabel
Specifies the label above the selection text entry
field.
DwtNvalue

DwtNokLabel

Specifies the label for the Ok push button. If the
label is a NULL string, the button is not displayed.

DwtNcancelLabel Specifies the label for the Cancel push button. If the
label is a NULL string, the button is not displayed.
DwtNactivateCallback
Specifies the callback function or functions called
when the user makes a selection. For this callback,
the reason is DwtCRActi vate.
DwtNcancelCallback
Specifies the callback function or functions called
when the user clicks on the Cancel button. For this
callback, the reason is DwtCRCancel.
DwtNnoMatchCallback
Specifies the callback function or functions called
when the user's selection does not have an exact
match with any items in the list box. This callback
is activated only if DwtNmustMatch is True.

6-42 Standard Menus and Dialog Box Widget Functions

For this callback, the reason is Dwt CRN oMa t ch.
DwtNvisibleltemsCount

Specifies the number of items displayed in the
selection widget's list box.
DwtN items

Specifies the items in the selection widget's list box.

DwtNi temsCount

Specifies the number of items in the selection
widget's list box.

DwtNmustMatch

Specifies a boolean value that, when True,
indicates that the selection widget checks whether the
user's selection has an exact match in the list box. If
the selection does not have an exact match, the
DwtNnoMatchCallback is activated. If the
selection has an exact match, the
DwtNacti vateCallback is activated.

6.8 Creating a File Selection Box Widget
A file selection box allows the user to specify a file name within your
application. To create an instance of the file selection widget, use
DwtFileSelection or DwtFileSelectionCreate. When calling
DwtFileSelection, you set the file selection box widget attributes
presented in the formal parameter list. For DwtFileSelectionCreate,
however, you specify a list of attribute name/value pairs that represent all the
possible file selection box widget attributes. After you create an instance of
this widget, you can manipulate it using the appropriate X intrinsics
functions. A description of each follows:
Widget DwtFileSelection (parent_widget, name, x, y,

title, value, dirmask,
visible_items_count, style, defaultyosition,
defaultyosition , callback,
help_callback)
Widget parent_widget;
char *name;
Position x, y;
DwtCompString title;
DwtCompString value;
DwtCompString dirmask;
int visible_items_count;
int style;
Boolean defaultyosition;
DwtCallbackPtr callback, help_callback;

Standard Menus and Dialog Box Widget Functions 6-43

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window. This argument sets the DwtNx core widget
attribute.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window. This argument sets the DwtNy core
widget attribute.

title

Specifies the text that appears in the banner of the file
selection box. This argument sets the DwtNt it 1 e attribute
associated with DwtDialogBoxPopupCreate.

value

Specifies the selected file. The file name appears in the text
entry field and is highlighted in the list box, if present. This
argument sets the DwtNval ue attribute associated with
DwtSelectionCreate.

dirmask

Specifies the directory mask u'sed in determining the files
displayed in the file selection list box. This argument sets
the DwtNdirMask attribute associated with
DwtFileSelectionCreate.

visible- items- count
Specifies the maximum number of files visible at one time in
the file selection list box. This argument sets the
DwtNvisibleIternsCount attribute associated with
DwtSelectionCreate.
style

Specifies the style of the pop-up dialog box widget. You can
pass DwtModal (modal) or DwtModeless (modeless).
This argument sets the DwtNstyle attribute associated
with DwtDialogBoxPopupCreate.

de/aultyositionSpecifies a boolean value that, when True, causes DwtNx
and DwtNy to be ignored and forces the default widget
position. The default widget position is centered in the
parent window. If False, the specified DwtNx and
DwtNy attributes are used to position the widget. This
argument sets the DwtNdefaultPosition attribute
associated with DwtDialogBoxCreate.
callback

6-44 Standard Menus and Dialog Box Widget Functions

and DwtNnoMatchCallback attributes associated with
DwtSelectionCreate.
help_callback Specifies the callback function or functions called when a
help request is made. This argument sets the
DwtNhelpCallback common widget attribute.
Widget DwtFileSelectionCreate (parent_widget, name,
override_arglist,
override_ argcount)
Widget parent_widget;
char * name;
ArgLi st override_argUst ;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtFileSelection and DwtFileSelectionCreate functions
create an instance of a file selection widget for the application to query the
user for a file selection and return its associated widget ID. This is a
subclass of the selection widget, which is a subclass of the dialog widget.
The file selection widget is a specialized pop-up dialog box, supporting either
modal or modeless formats.
A file selection widget contains the following:
•

A list box displaying the file names from which to choose

•

A directory mask text entry field

•

A selection text entry field

•

An Apply push button to apply the dirmask to generate a new list of
files

•

An Ok push button to inform the application that the user made a
selection

•

A Cancel push button to inform the application that the user canceled a
selection

Note that the callback data structure also includes the current DwtNval ue
and DwtNdirMask. This allows user input text and directory information
to be passed back.

Standard Menus and Dialog Box Widget Functions 6-45

The file selection widget supports remote file search between nodes on a
network. You can perform remote file searches from VMS to ULTRIX
systems, but currently not from ULTRIX to VMS systems.
The file selection widget follows the same rules for geometry management as
its superc1ass the selection widget. The selection widget follows the same
rules for geometry management as its superc1ass the dialog widget.
Consequently, the selection widget allows only one child and it places the
child between the list box and the push buttons. The child cannot be a
gadget. For more information on the geometry management associated with
the dialog widget, see Section 5.1.2.
The file selection widget follows the same rules for resizing as its superc1ass
the selection widget. The selection widget follows the same rules for
resizing as its superc1ass the dialog widget. For more information on the
resizing associated with the dialog widget, see the DwtNresize attribute
associated with DwtDialogBoxCreate.
The following sections discuss these aspects of the file selection box widget:

6.8.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
DwtCompString value;
int value_len;
DwtCompString dirmask;
int dirmask len;
DwtFileSelectionCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActi vate

The user activated the Ok push button.

DwtCRCancel

The user activated the Cancel button.

DwtCRHelpRequested

The user selected help somewhere in the
file selection box.

The event member is a pointer to the Xlib structure XEvent, which

6-46 Standard Menus and Dialog Box Widget Functions

describes the event that generated this callback. This structure is a union of
the individual structures declared for each event type. For information on
XEvent and event processing, see the Guide to the Xlib Library: C
Language Binding. The value member is set to the current selection when the
callback occurred. The value_len member is set to the length of the selection
compound-string. The dirmask member is set to the current directory mask
when the callback occurred. The dirmask_len member is set to the length of
the directory mask compound-string.

6.8.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the file selection box widget is:

•
•
•
•
•
•

core
composite
constraint
dialog
selection
file selection

Based on this class hierarchy, the file selection widget inherits attributes from
the core, composite, constraint, dialog, and selection widgets. Note that you
cannot set the attributes for the composite or constraint widgets; therefore,
they are not shown.
Table 6-13 lists the attributes inherited by the file selection box widget. For
descriptions of the core and common attributes, see Chapter 1.

Table 6-13: Attributes Inherited by the File Selection Box Widget
Attribute Name

Data Type

Default

Position
Position
Dimension

Core Attributes
DwtNx
DwtNy
DwtNwidth

Standard Menus and Dialog Box Widget Functions 6-47

Table 6-13:

(continued)

Attribute Name

Data Type

Default

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

The height of the list box, plus
the height of the text edit field,
plus the height of the label, plm
three times
DwtNmarginHeight.
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive an
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char
unsigned char
DwtCallbackptr
XtTranslations
Dimension
Dimension
Boolean
Boolean
unsigned char

Default foreground color
Default foreground color
NULL
NULL
The default XUI Toolkit font
NULL
DwtDirectionRightDown
DwtFontUnits
DwtModal
NULL
NULL
5 pixels
5 pixels
False
True
DwtResizeGrowOnly

Dialog Pop-Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNstyle
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize

6-48 Standard Menus and Dialog Box Widget Functions

Table 6-13:

(continued)

Attribute Name

Data Type

Default

DwtNnoResize

Boolean

DwtNtitle
DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

DwtCompString
DwtCallbackPtr
DwtCallbackPtr
Boolean

True (that is, no window
manager resize button)
"Open"

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
Widget
Widget

NULL
NULL
T rue for modal dialog box
False for modeless dialog box
True

NULL
NULL

Selection Attributes
DwtNlabel
DwtNvalue
DwtNokLabel
DwtNcancelLabel
DwtNactivateCallback
DwtNcancelCallback
DwtNnoMatchCallback
DwtNvisibleltemsCount
DwtNitems
DwtNitemsCount
DwtNmustMatch
DwtNselectionLabel

6.8.3

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
int
DwtCompString *
int
Boolean
DwtCompString

"Items"
"Ok"
"Cancel"

NULL
NULL
NULL
8

NULL
Zero
False
"Files in"

Widget-Specific Attributes
Table 6-14 lists the widget-specific attributes for the file selection box
widget. Descriptions of these attributes follow the table.

Table 6-14: Widget-Specific Attributes for the File Selection Box
Widget
Attribute Name

Data Type

Default

DwtNfilterLabel
DwtNapplyLabel

DwtCompString
DwtCompString

"File filter"
"Filter"

Standard Menus and Dialog Box Widget Functions 6-49

Table 6-14:

(continued)

Attribute Name

Data Type

Default

DwtNdirMask
DwtNdirSpec
DwtNfileSearchProc

DwtCompString
DwtCompString
VoidProc

"*.*"
FileSelectionSearch

CULTRIX default directory file
search function)
DwtNlistUpdated
DwtNfileToExternProc
DwtNfileToInternProc
DwtNmaskToExternProc
DwtNmaskToInternProc

Boolean
VoidProc
VoidProc
VoidProc
VoidProc

False

NULL
NULL
NULL
NULL

DwtNfil terLabel Specifies the label for the search filter located above
the text-entry field.
DwtNapplyLabel

Specifies the label for the Apply push button.

DwtNdirMask

Specifies the directory mask used in detennining the
files displayed in the file selection list box.

DwtNdirSpec

Specifies the full ULTRIX file specification. This
attribute is write only and cannot be modified by
XtSetVal ues.

DwtNfileSearchProc
Specifies a directory search procedure to replace the
default file selection search procedure. The file
selection widget's default file search procedure
fulfills the needs of most applications. However, it is
impossible to cover the requirements of all
applications; therefore, you can replace the default
search procedure.

You call the file search procedure with two
arguments: the file selection widget and the
DwtFileSelectionCallbackStruct
structure. The callback structure contains all required
information to conduct a directory search, including
the current file search mask. Once called, it is up to
the search routine to generate a new list of files and
update the file selection widget by using
xtSetValues.
You must set these attributes: DwtNi terns,
DwtNi ternsCount, DwtNlistUpdated, and

6-50 Standard Menus and Dialog Box Widget Functions

DwtNdirSpec. Set DwtNi tems to the new list
of files. If there are no files, set this attribute to
NULL. This argument sets the DwtNitems
attribute associated with DwtSelectionCreate.

If there are no files set DwtNi temsCount to zero.
This argument sets the DwtNi temsCount
associated with DwtSelectionCreate. Always
set DwtNlistUpdated to True when updating
the file list using a search procedure, even if there are
no files. Setting DwtNdirSpec is optional, but
recommended. Set this attribute to the full file
specification of the directory searched. The directory
specification is displayed above the list box.
DwtNlistUpdated Specifies an attribute that is set only by the file
search procedure. Set to True, if the file list has

been updated.
DwtNfileToExternProc

Converts native, internal file names to custom,
external file names displayed to the user.
DwtNfileTolnternProc

Converts custom, external file names displayed to the
user to native, internal file names.
DwtNmaskToExternProc

Converts native, internal directory masks to custom,
external directory masks displayed to the user.
DwtNmaskTolnternProc

Converts custom, external directory masks displayed
to the user to native, internal directory masks.

6.9 Initiating a Search with a Directory Mask Option
To initiate a search with a directory mask option, use
DwtFileSelectionDoSearch.
void DwtFileSelectionDoSearch (widget, dirmask)
FileSelectionWidget widget;
DwtCompString dirmask;

widget

Specifies the pointer to the file selection widget data
structure.

dirmask

Specifies the directory mask used in detennining the files
displayed in the file selection list box. This is an optional
attribute. If you do not specify a directory mask, the default

Standard Menus and Dialog Box Widget Functions 6-51

directory mask is used. This argument sets the
DwtNdirMask attribute associated with
DwtFileSelectionCreate.
The file selection widget initiates file searches when any of the following
occur:
•

The file selection widget becomes visible (managed).

•

You use XtSetValues to change the directory mask.

•

The user clicks on the Apply push button.

•

The application calls DwtFileSelectionDoSearch, which is
another way for applications to initiate a directory search. This may be
useful, for example, when the application creates a new file and wants
to reflect this change in a mapped file search widget.

6-52 Standard Menus and Dialog Box Widget Functions

Gadget Functions

The XUI Toolkit provides gadgets, which are reduced functionality widgets.
The main difference between a gadget and a widget is that a gadget does not
have an associated X window. This chapter discusses the following:
•

Classes associated with gadgets

•
•

Advantages of using gadgets
X intrinsics and convenience functions used with gadgets

In addition, the chapter explains the functions you use to create instances of
the following:

7.1

•

Label gadget

•

Separator gadget

•

Push button gadget

•

Toggle button gadget

•

Pull-down menu entry gadget

Classes Associated with Gadgets
Table 7-1 lists each gadget and its associated class and possible parent
widgets.

Table 7-1: Gadget Classes and Parents
Gadget

Class

Parent

DwtLabelGadgetCreate

labelgadgetclass

The parent widget
must be a menu
class widget
(Menu, Menu Bar,
Pull-Down Menu,
Pop-Up Menu,
Radio Box) or a
dialog box class
widget.

Table 7-1:

(continued)

Gadget

Class

Parent

DwtSeparatorGadgetCreate

separatorgadgetclass

Same as for
DwtLabelGadgetCrec

DwtPushButtonGadgetCreate

pushbuttongadgetclass

Same as for
DwtLabelGadgetCrec

DwtToggleButtonGadgetCreate

togglebuttongadgetclass

Same as for
DwtLabelGadgetCrec

Note that because a parent widget must do work for the gadget and a gadget
does not have an associated X window, you cannot place gadgets within a
composite widget.

7.2 Advantages of Using Gadgets
The following are advantages of using gadget widgets:
•

Reduced creation time -

Gadgets have far less resources than widgets

•

Reduced memory usage - Gadget instance records are much smaller
than widget instance records

•

Reduced window count window

Gadgets do not create an associated X

•

Increased drawing speed window

A side-effect of not having a separate

7.3 X Intrinsics and Convenience Functions Used with
Gadgets
The following functions are supported by
DwtToggleButtonGadgetCreate:
•

DwtToggleButtonGetState

•

DwtToggleButtonSetState

The following X intrinsics functions are supported by all the gadgets for
calling by applications:
•

XtDestroyWidget

•

XtSetVal ues

7-2 Gadget Functions

•
•

XtClass

•

XtIsSubclass

•

XtSuperclass

•
•
•
•
•

XtCheckSubclass

•
•
•

XtHasCallbacks

XtGetValues

XtAddCallback
XtAddCallbacks
XtRemoveCallback
XtRemoveCallbacks
XtSetSensitive
XtConvert

7.4 Creating a Label Gadget
To create an instance of the label gadget, use DwtLabelGadgetCreate.
For DwtLabelGadgetCreate, just like the usual low-level functions,
you specify a list of attribute name/value pairs that represent all the possible
label gadget attributes. A description of this function follows:
Widget DwtLabelGadgetCreate (parent_widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char * name;
ArgList override_arglist;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_argiistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtLabelGadgetCreate function creates an instance of the label
gadget and returns its associated gadget ID. A label gadget is similar in
appearance and semantics to a label widget. Like all gadgets, the label
gadget does not have a window but uses the window of the closest antecedent
widget. Thus, the antecedent widget provides all event dispatching for the
gadget. This currently restricts gadgets to being descendents of menu or

Gadget Functions 7-3

dialog class (or subclass) widgets. Drawing information such as font and
color are also those of the closest antecedent widget.
Because a label gadget is not a subclass of composite, children are not
supported.
The label gadget does nothing on a resize by its parents.
The following sections discuss these aspects of the label gadget:

7.4.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRHelpRequested

The user selected Help.

7.4.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the label gadget is:
•

object

•

rectangle

•

label gadget

Table 7-2 lists the attributes inherited by the label gadget.

7-4 Gadget Functions

Table 7-2: Attributes Inherited by the Label Gadget

7.4.3

Attribute Name

Data Type

Default

Rectangle Attributes
DwtNx

position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
The width of the label plus
margins
The height of the label plus
margins
zero pixels
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

Widget-Specific Attributes
Table 7-3 lists the widget-specific attributes of the label gadget. Following
the table are descriptions of each attribute.

Table 7-3: Widget-Specific Attributes for DwtLabelGadgetCreate
Attribute Name

Data Type

Default

DwtNlabel
DwtNalignment
DwtNdirectionRToL
DwtNhelpCallback

DwtCompString
unsigned char
Boolean
DwtCallbackPtr

Widget name
DwtAlignmentCenter
False
NULL

DwtNlabel

Specifies the label for the text style.

DwtNalignment

Specifies the label alignment for text style. You can
pass DwtAlignmentCenter (center alignment),
DwtAlignmentBeginning (alignment at the
beginning), or DwtAlignmentEnd (alignment at
the end).

DwtNdirectionRToLSpecifies a boolean value that, when False,
indicates that the text is drawn from left to right. If
Gadget Functions 7-5

True, the text is drawn from right to left.
DwtNhelpCallback Specifies the callback function or functions called
when a help request is made.

7.5 Creating a Push Button Gadget
To create an instance of the push button gadget, use
DwtPushBut tonGadgetCreate. For
DwtPushButtonGadgetCreate, just like the usual low-level functions,
you specify a list of attribute name/value pairs that represent all the possible
push button gadget attributes. A description of this function follows:
Widget DwtPushButtonGadgetCreate (parent_widget, name,
override_arglist,
override_argcount)
Widget parent_widget;
char * name ;
ArgList override_arglist;
int override_argcount ;

parent_widget Specifies the parent widget ID.

Specifies the name of the created widget.

name

override_ arglistSpecifies the application override argument list.
override_ argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtPushButtonGadgetCreate function creates an instance of the
push button gadget and returns its associated gadget ID. Because drawing
information such as font and color are those of the closest antecedent, the
sizing is affected by the font and label. See DwtLabelGadgetCreate.
Because a push button gadget is not a subclass of composite, children are not
supported. The push button gadget widget does nothing on a resize by its
parents.
The following sections discuss these aspects of the push button gadget:
•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

7-6 Gadget Functions

7.5.1

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRActi vate

The user activated the push button.

DwtCRHelpRequested

The user selected Help.

7.5.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the push button gadget is:
•

object

•

rectangle

•

label gadget

•

push button gadget

Table 7-4 lists the attributes inherited by the push button gadget.

Table 7-4: Attributes Inherited by the Push Button Gadget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

position

Detennined by the geometry
manager
Detennined by the geometry
manager

Rectangle Attributes

Gadget Functions 7-7

Table 7-4:

7.5.3

(continued)

Attribute Name

Data Type

Default

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

The width of the label plus
margins
The height of the label plus
margins
1 pixel
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

Widget-Specific Attributes
Table 7-5 lists the widget-specific attributes of the push button gadget.
Following the table are descriptions of each attribute.

Table 7-5: Widget-Specific Attributes for the Push Button
Gadget
Attribute Name

Data Type

Default

DwtNlabel
DwtNactivateCallback
DwtNacceleratorText
DwtNbuttonAccelerator

DwtCompString
DwtCallbackptr
DwtCompString
char *

NULL
NULL
NULL
NULL

DwtNlabel

Specifies the push button label.

DwtNactivateCallback
Specifies the callback function or functions called
when the push button is activated. The button is
activated when the user presses and releases MB 1
while the pointer is inside the push button gadget.
For this callback, the reason is DwtCRActi vate.
DwtNacceleratorText
Specifies the compound-string text displayed for the
accelerator.

7-8 Gadget Functions

DwtNbuttonAccelerator
Sets an accelerator on a push button widget. This is
the same as the DwtNtranslations core
attribute except that only the left side of the table is
to be passed as a character string, not compiled. The
application is responsible for calling
XtlnstallAllAccelerators to install the
accelerator where the application needs it.

7.6 Creating a Separator Gadget
To create an instance of the separator gadget, use
DwtSeparatorGadgetCreate. For
DwtSeparatorGadgetCreate, just like the usual low-level functions,
you specify a list of attribute name/value pairs that represent all the possible
separator gadget attributes. A description of this function follows:
Widget DwtSeparatorGadgetCreate (parent_widget, name,
override_arglist,
override_argcount )
Widget parent_widget;
char *name;
ArgList override_arglist;
int override_argcount;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _arglist).
The DwtSeparatorGadgetCreate function creates an instance of the
separator gadget and returns its associated gadget ID. A separator gadget is
similar in appearance and semantics to a separator widget. Like all gadgets,
DwtSeparatorGadgetCreate does not have a window but uses the
window of the closest antecedent widget. Thus, the antecedent widget
provides all event dispatching for the gadget. This currently restricts gadgets
to being descendents of menu or dialog class (or subclass) widgets.
The separator gadget widget does nothing on a resize by its parents. Because
a separator gadget is not a subclass of composite, children are not supported.
The following sections discuss these aspects of the separator gadget:
•

Widget class hierarchy and inherited attributes

Gadget Functions 7-9

•

7.6.1

Widget-specific attributes

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the separator gadget widget is:
•

object

•

rectangle

•

separator gadget

Table 7-6 lists the attributes inherited by the separator gadget.

Table 7-6: Attributes Inherited by the Separator Gadget
Attribute Name

Data Type

Default

Rectangle Attributes
DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
3 pixels
3 pixels
zero

True
The bitwise AND of the parent
widget's DwtNsensitive and

DwtNancestorSensitive
attributes

7.6.2

Widget-Specific Attributes
Table 7-7 lists the widget-specific attribute of the separator gadget.
Following the table is a description of the attribute.

Table 7-7: Widget-Specific Attribute for the Separator Gadget
Attribute Name

Data Type

Default

DwtNorientation

unsigned char

DwtOrientationHorizontal

7-10 Gadget Functions

DwtNorientation Specifies whether the separator is displayed vertically

or horizontally. You can pass
DwtOrientationHorizontalm
DwtOrientationVertical. A separator gadget

draws a centered single pixel line between the
appropriate margins. For example, a horizontal
separator draws a horizontal line from the left margin
to the right margin. It is placed vertically in the
middle of the gadget.

7.7 Creating a Toggle Button Gadget
To create an instance of the toggle button gadget, use
Dwt ToggleButtonGadgetCreate. For
DwtToggleButtonGadgetCreate, just like the usual low-level
functions, you specify a list of attribute name/value pairs that represent all
the possible toggle button gadget attributes. A description of this function
follows:
Widget DwtToggleButtonGadgetCreate (parent widget, name,

override arglist,
override_argcount)
Widget parent_widget;
char * name;
ArgLi st override_arglist ;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtToggleButtonGadgetCreate function creates an instance of
the toggle button gadget and returns its associated gadget ID. A toggle
button gadget is similar in appearance and semantics to a toggle button
widget. Like all gadgets, Dwt ToggleButtonGadgetCreate does not
have a window but uses the window of the closest antecedent widget. Thus,
the antecedent widget provides· all event dispatching for the gadget. This
currently restricts gadgets to being descendents of menu or dialog class (or
subclass) widgets.
The sizing is affected by the font and label. See
DwtLabelGadgetCreate for more information. The indicator size is
based on the height of the toggle button. The indicator width is equal to the

Gadget Functions 7-11

indicator height.
The following sections discuss these aspects of the toggle button gadget:

7.7.1

•
•

Callback information
Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
int value;
DwtTogglebuttonCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:
DwtCRVal ueChanged

The user activated the toggle button to
change state.

DwtCRHelpRequested

The user selected Help.

7.7.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the toggle button gadget widget is:
•

object

•

rectangle

•

label gadget

•

toggle button gadget

Table 7-8 lists the attributes inherited by the toggle button gadget.

7-12 Gadget Functions

Table 7-8: Attributes Inherited by the Toggle Button Gadget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
The width of the label plus
margins
The height of the label plus
margins
zero
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

Rectangle Attributes

Label Attributes
DwtNlabel
DwtNalignment
DwtNdirectionRToL
DwtNhelpCallback

7.7.3

DwtCompString
unsigned char
Boolean
DwtCallbackptr

Widget name
DwtAlignmentCenter
False
NULL

Widget-Specific Attributes
Table 7-9 lists the widget-specific attributes of the toggle button gadget.
Following the table are descriptions of each attribute.

Table 7-9: Widget-Specific Attributes for the Toggle Button
Gadget
Attribute Name

Data Type

Default

DwtNshape
DwtNvalue
DwtNvisibleWhenOff
DwtNvalueChangedCallback
DwtNbuttonAccelerator
DwtNacceleratorText

unsigned char
Boolean
Boolean
DwtCallbackptr
char *
DwtCompString

DwtRectangular
False
True
NULL
NULL
NULL

Gadget Functions 7-13

Table 7-9:
Attribute Name

(continued)
Data Type

Default

DwtNshape

Specifies the toggle button indicator shape. You can
pass DwtRectangular or DwtOval.

DwtNvalue

Specifies a boolean value that, when False,
indicates the button state is off. If True, the button
state is on.

DwtNvisibleWhenOff
Specifies a boolean value that, when True,
indicates that the toggle button is visible when in the
off state.
DwtNvalueChangedCallback
Specifies the callback function or functions called
when the toggle button value was changed. For this
callback, the reason is DwtCRVal ueChanged.
DwtNbuttonAccelerator
Sets an accelerator on a toggle button widget. This
is the same as the DwtNtranslations core
attribute except that only the left side of the table is
to be passed as a character string, not compiled. The
application is responsible for calling
XtInstallAIIAccelerators to install the
accelerator where the application needs it.
DwtNacceleratorText
Specifies the compound-string text displayed for the
accelerator.

7.8 Creating a Pull-Down Menu Entry Gadget
To create an instance of the pull-down menu entry gadget, use
DwtPullEntryGadgetCreate. For
DwtPullEntryGadgetCreate, just like the usual low-level functions,
you specify a list of attribute name/value pairs that represent all the possible
pull-down menu entry gadget attributes. A description of this function
follows:

7-14 Gadget Functions

Widget DwtPullEntryGadgetCreate (parent_widget, name,
override_arglist,
override_argcount)
Widget parent_widget;
char * name;
ArgList override_arglist;
int override_argcount ;

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

override_arglistSpecifies the application override argument list.
override argcount
Specifies the number of attributes in the application override
argument list (override _arglist).

The DwtPullEntryGadgetCreate function creates an instance of the
pull-down menu entry gadget and returns its associated gadget ID.
A pull-down menu entry gadget is similar in appearance and semantics to a
pull-down menu entry widget. Like all gadgets, it does not have a window
but uses the window of the closest antecedent widget. This gadget must be a
child of a menu class widget.
Because a pull-down menu entry gadget is not a subclass of composite,
children are not supported.
The sizing of the gadget is affected by the font and the label. See the section
on geometry management and resizing for the DwtPullDownMenuEntry
function for more information. The following sections discuss these aspects
of the pull-down menu entry gadget:

7.8.1

•

Callback information

•

Widget class hierarchy and inherited attributes

•

Widget-specific attributes

Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this
callback was invoked. For this callback, the reason member can be set to:

Gadget Functions 7-15

DwtCRActi vate

The user selected the pull-down menu
entry.

DwtCRHelpRequested

The user selected Help.

7.8.2

Widget Class Hierarchy and Inherited Attributes
The widget class hierarchy for the pull-down menu entry gadget is:
•
•

object
rectangle

•
•

label gadget
pull-down menu entry gadget

Table 7-10 lists the attributes inherited by the pull down menu entry gadget.

Table 7-10: Attributes Inherited by the Pull-Down Menu Entry
Gadget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive

Dimension
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
The label width, plus the hotspot
width, plus 2 times
DwtNmarginWidth
The text label or pixmap label
height plus 2 times
DwtNmarginHeight
Zero pixels
True

Rectangle Attributes

7-16 Gadget Functions

Table 7-10:

(continued)

Attribute Name

Data Type

Default

DwtNancestorSensitive

Boolean

The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

DwtCompString
unsigned char
Boolean
DwtCallbackPtr

Widget name
DwtAlignmentCenter
False
NULL

Label Gadget Attributes
DwtNlabel
DwtNalignment
DwtNdirectionRToL
DwtNhelpCallback

7.8.3

Widget-Specific Attributes
Table 7-11 lists the widget-specific attributes of the pull-down menu entry
gadget. Following the table are descriptions of each attribute.

Table 7-11: Widget-Specific Attributes for the Pull-Down Menu
Entry Gadget
Attribute Name

Data Type

Default

DwtNsubMenuld
DwtNactivateCallback
DwtNpullingCallback

Widget
DwtCallbackptr
DwtCallbackptr

NULL
NULL
NULL

DwtNsubMenuld

Specifies the widget ID of the submenu that will be
displayed when the pull-down menu is activated.

Gadget Functions 7-17

You can use this callback to defer the creation of the
submenu. For this callback, the reason is
DwtCRActi vate.

7-18 Gadget Functions

PART THREE: OTHER TOOLKIT FUNCTIONS

Cut and Paste Functions

An application can interface to the xm Toolkit clipboard through calls to the
cut and paste functions. For more information, see the XU! Style Guide.

This chapter begins with an introduction to the cut and paste functions
followed by a brief discussion of the formats. The rest of the chapter
discusses the functions you can use to:

8.1

•

Set up storage and data structures

•

Indicate that the application no longer wants to supply a data item

•

Cancel a copy to clipboard

•

Lock the clipboard

•

Unlock the clipboard

•

Retrieve a data item from the clipboard

•

Copy a data item to the clipboard

•

Place data in the clipboard

•

Return the number of data item formats

•

Return a specified format name

•

Return the length of the stored data

•

Return a list of data ID/private ID pairs

•

Copy a data item passed by name

•

Delete the last item placed on the clipboard

•

Introduction to the Cut and Paste Functions
If your application needs to give the user maximum access to the clipboard,
the following menu items should be included in the Edit menu:

•

Cut
When the user chooses this item, the application calls
DwtBeginCopyToClipboard, DwtCopyToClipboard,and
DwtEndCopyToClipboard to copy the data in whatever formats it

desires. The application should then delete the cut items from the
user's display.
•

Copy
The same as Cut except the items are not deleted.

•

Paste
When the user chooses this item, the application calls
DwtCopyFromClipboard to obtain the data in some format. The
application then allows the user to place the data on the display.

The user can perform the following actions on an application by using the
clipboard:
•

Undo Cut
The application redraws the deleted items. The application then calls
DwtUndoCopyToClipboard to delete the items from the clipboard.

•

Redo Cut
The application copies the items to the clipboard.

•

Undo Copy
The application calls DwtUndoCopyToClipboard.

•

Redo Copy
The application copies the items to the clipboard.

•

Undo Paste
The application saves the pasted items for a possible later Redo Paste.

•

Redo Paste
The application saves the pasted items for a possible later Undo Paste.

The clipboard is not involved with an Undo Paste or a Redo Paste. This is
because between the Paste and the Undo Paste or between the Undo Paste
and the Redo Paste, the clipboard might be changed by the user either
directly or indirectly.
Copying a large piece of data to the clipboard can take time. It is possible
that, once copied, no application will ever request that data. The XUI
Toolkit provides a mechanism so that an application does not need to
actually pass data to the clipboard until the data has been requested by some
application. Instead, the application passes format and length information to
the clipboard functions, along with a widget ID and a callback function
address. The widget ID is needed for communications between the clipboard
functions in the application that owns the data and the clipboard functions in
the application that requests the data. Your callback functions are
responsible for copying the actual data to the clipboard (via

8-2 Cut and Paste Functions

DwtReCopyToClipboard). The callback function is also called if the
data item is removed from the clipboard, and the actual data is therefore no
longer needed.
For more information on passing data by name, see
DwtBeginCopyToClipboard, DwtCopyToClipboard,and
DwtReCopyToClipboard.

8.2 ICCCM Compliant Functions and ICCCM Formats
Four new cut and paste functions have been added to ensure compliance with
the Inter-Client Communications Conventions Manual (ICCCM). The
ICCCM manual defines conventions for using the global selection
mechanism that allows compliant clients to communicate with each other.
These new functions include:
•

DwtStartCopyToClipboard

•

DwtStartCopyFromClipboard

•

DwtEndCopyFromClipboard

•

DwtClipboardRegisterFormat

Several of the cut and paste functions use the format_name argument, which
specifies the format of the data stored on the clipboard. The formats
specified by the ICCCM are 8-bit, 16-bit, and 32-bit.
It is recommended that applications use the ICCCM formats. If an
application uses a non-ICCCM format that is not an 8-bit format, it must
register the format with the cut and paste functions using
DwtClipboardRegisterFormat. Failure to do so may result in
unexpected results when trying to cut and paste between clients running on
different platforms.
Table 8-1 lists the ICCCM format names, format lengths, and a description
of the formats.

Table 8-1: Data Format Names
Format Name

Format Length

Description

TARGETS
MULTIPLE
TIMESTAMP

32
32
32

STRING
TEXT
LIST_LENGTH
PIXMAP

8
32
32

List of valid target atoms
Look in the ConvertS election property
Timestamping used to acquire
selection
ISO Latin 1 (+TAB+NEWLINE) text
Text in owner's encoding
Number of disjoint parts of selection
Pixmap ID

Cut and Paste Functions 8-3

Table 8-1:

(continued)

Format Name

Format Length

Description

DRAWABLE
BITMAP
FOREGROUND
BACKGROUND
COLORMAP
ODIF

32
32
32
32
32
8

OWNER_OS
FILE_NAME
HOST_NAME
CHARACTER_POSITION
LINE_NUMBER
COLUMN_NUMBER
LENGTH
USER
PROCEDURE
MODULE
PROCESS
TASK
CLASS
NAME
CLIENT_WINDOW

8
8
8
32
32
32
32
8
8
8
32 or 8
32 or 8
8
8
32

Drawable ID
Bitmap ID
Pixel value
Pixel value
Colormap ID
ISO Office Document Interchange
Format
Operating system of owner
Full path name of a file
See WM_CLIENT_MACHINE
Start and end of selection in bytes
Start and end line numbers
Number of bytes in selection
Name of user running owner
Name of selected procedure
Name of selected module
Process ID of owner
Task ID of owner
Class of owner-See WM_CLASS
Name of owner-See WM_NAME
Top-level window of owner

For information on the built-in selection property names
WM_CLIENT_MACHINE, WM_CLASS, and WM_NAME, see the Guide
to the Xlib Library: C Language Binding.

8.3 Setting Up Storage and Data Structures
To set up storage and data structures to receive clipboard data, use
DwtBeginCopyToClipboardor DwtStartCopyFromClipboard
Because it complies with the ICCCM conventions, use of
DwtStartCopyToClipboard is recommended over
DwtBeginCopyToClipboard. Each of these functions is discussed in
the following sections.

8-4 Cut and Paste Functions

8.3.1

Using DwtStartCopyFromClipboard to Set Up Storage and
Data Structures
To comply with ICCCM conventions when setting up storage and data
structures, use DwtStartCopyToClipboard.
int DwtStartCopyToClipboard (display, window, clip label,

time, widget, callback, - item_id)
Display * display;
Window window;
DwtCompString clip_label;
Time time;
Widget widget;
VoidProc callback;
long * item_id;

display

Specifies a pointer to the Display structure that was
returned in a previous call to XOpenDisplay. For
information on XOpenDisplay and the Display
structure, see the Guide to the Xlib Library: C Language
Binding.

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ill to each clipboard function that it calls.
Specifies the label to be associated with the data item. This
argument is used to identify the data item, for example, in a
clipboard viewer. An example of a label is the name of the
application that places the data in the clipboard.

time

Specifies the timestamping of the event that triggered the
copy.

widget

Specifies the ID of the widget that will receive messages
requesting data previously passed by name. This argument
must be present in order to pass data by name. Any valid
widget ID in your application can be used. All message
handling is done by the cut and paste functions.

callback

Specifies the address of the callback function that is called
when the clipboard needs data that was originally passed by
name. This is also the callback to receive the DELETE
message for items that were originally passed by name. This
argument must be present in order to pass data by name.

item id

Specifies the number assigned to this data item. The
application uses this number in calls to
DwtCopyToClipboar~ DwtEndCopyToClipboar~

and DwtCancelCopyToClipboard.

Cut and Paste Functions 8-5

The DwtStartCopyToClipboard function sets up storage and data
structures to receive clipboard data. An application calls
DwtStartCopyToClipboard during a cut or copy operation. The data
item that these structures receive through calls to DwtCopyToClipboard
then becomes the next item to be pasted (the next-paste item) in the clipboard
after the call to DwtEndCopyToClipboard.
DwtStartCopyToClipboardislike DwtBeginCopyToClipboard
except that it has the time argument to support the ICCCM clipboard
selection mechanism. To perform cut and paste operations between your
application and an application using the ICCCM clipboard selection
mechanism, you must use DwtStartCopyToClipboard and provide a
timestamping value for time, not a Current Time value. Use of the value
CurrentTime for time may cause the ICCCM interface to fail.
The window and callback arguments must be present in order to pass data by
name.
The callback format is as follows:
function name (widget, data_id, private_id, reason)
Widget * widget ;
int * data id;
int * private_id;
int * reason;
widget

Specifies the ID of the widget passed to
DwtStartCopyToClipboard.

data id

Specifies the identifying number returned by
DwtCopyToClipboard, which identifes the pass-by-name
data.

private_id

Specifies the private information passed to
DwtCopyToClipboard.

reason

Specifies the reason, which is either
DwtCRClipboardDataDelete or
DwtCRClipboardDataRequest.

This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

8-6 Cut and Paste Functions

8.3.2

Using DwtBeginCopyToClipboard to Set Up Storage and
Data Structures
To set up storage and data structures, use DwtBeginCopyToClipboard.
int DwtBeginCopyToClipboard (display, window, clip_label,
Display * display;
Window window;
DwtCompString clip label;
Widget widget;
VoidProc callback;
long * item_id;

widget, callback, itern_id)

display

Specifies a pointer to the Display structure that was
returned in a previous call to XOpenDisplay. For
infonnation on XOpenDisplay and the Display
structure, see the Guide to the Xlib Library: C Language
Binding.

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.
Specifies the label to be associated with the data item. This
argument is used to identify the data item, for example, in a
clipboard viewer. An example of a label is the name of the
application that places the data in the clipboard.

widget

callback

item id

Specifies the number assigned to this data item. The
application uses this number in calls to
DwtCopyToClipboar~ DwtEndCopyToClipboar~

and DwtCancelCopyToClipboard.
The DwtBeginCopyToClipboard function sets up storage and data
structures to receive clipboard data. An application calls
DwtBeginCopyToClipboard during a cut or copy operation. The data
item that these structures receive then becomes the next-paste item in the

Cut and Paste Functions 8-7

clipboard.
The widget and callback arguments must be present in order to pass data by
name. The callback format is as follows:
function name (widget, data_id, private_id, reason)
Widget * widget ;
int *data_id;
int * private_id ;
int * reason;

widget

Specifies the ID of the widget passed to
DwtBeginCopyToClipboard.

data id

Specifies the identifying number returned by
DwtCopyToClipboard, which identifes the pass-by-name
data.
Specifies the private information passed to
DwtCopyToClipboar~

reason

Specifies the reason, which is either
DwtCRClipboardDataDelete or
DwtCRClipboardDataRequest.

This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

8.4 Indicating That the Application No Longer Wants to
Supply a Data Item
To indicate that the application is no longer willing to supply a data item to
the clipboard, use DwtCancelCopyFormat.

8-8 Cut and Paste Functions

int DwtCancelCopyFormat (display, window, data_id)
Display * display;
Window window;
int data_id;

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

data id

Specifies an identifying number assigned to the data item that
uniquely identifies the data item and the format. This was
assigned to the item when it was originally passed by
DwtCopyToClipboard.

The DwtCancelCopyFormat function indicates that the application will
no longer supply a data item to the clipboard that the application had
previously passed by name.
This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

8.5 Canceling a Copy to Clipboard
To cancel the copy to clipboard that is in progress, use
DwtCancelCopyToClipboard
void DwtCancelCopyToClipboard (display, window, item_id)
Display * display ;
Window window;
long item_id;

display

Specifies a pointer to the Display structure that was
returned in a previous call to XOpenDisplay. For

Cut and Paste Functions 8-9

infonnation on XOpenDisplay and the Display
structure, see the Guide to the Xlib Library: C Language
Binding.
window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

item id

Specifies the number assigned to this data item. This number
was returned by a previous call to
DwtBeginCopyToClipboard.

The DwtCancelCopyToClipboard function cancels the copy to
clipboard that is in progress. DwtCancelCopyToClipboard also frees
up temporary storage. If DwtCancelCopyToClipboard is called, then
DwtEndCopyToClipboard does not have to be called. A call to
DwtCancelCopyToClipboard is valid only after a call to
DwtBeginCopyToClipboard and before a call to
DwtEndCopyToClipboard.

8.6 Locking the Clipboard
To lock the clipboard from access by other applications, use
DwtClipboardLock.
int DwtClipboardLock (display, window)
Display * display;
Window window;
display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

The DwtClipboardLock function locks the clipboard from access by
another application until you call DwtClipboardUnlock. All clipboard
functions lock and unlock the clipboard to prevent simultaneous access. The
DwtClipboardLock and DwtClipboardUnlock functions allow the
application to keep the clipboard data from changing between calls to the
inquire functions and other clipboard functions. The application does not
need to lock the clipboard between calls to
DwtBeginCopyToClipboardand DwtEndCopyToClipboard.

8-10 Cut and Paste Functions

If the clipboard is already locked by another application,
DwtClipboardLock returns an error status.
Multiple calls to DwtClipboardLock by the same application increase
the lock level.
This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

8.7 Unlocking the Clipboard
To unlock the clipboard, use DwtClipboardUnlock.
int DwtClipboardUnlock (display, window, remove_ali_locks)
Display * display;
Window window;
Boolean remove_ail_locks;

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ill to each clipboard function that it calls.

remove all 10cksSpecifies a boolean value that, when True, indicates that
- all nested locks should be removed. If False, indicates
that only one level of lock should be removed.
The DwtClipboardUnlock function unlocks the clipboard, enabling it to
be accessed by other applications.
If mUltiple calls to DwtClipboardLock have occurred, then the same
number of calls to DwtClipboardUnlock is necessary to unlock the
clipboard, unless the remove_ali_locks argument is True.
This function returns one of these status return constants:

Cut and Paste Functions 8-11

ClipboardSuccess
ClipboardLocked

8.8 Retrieving a Data Item from the Clipboard
You can use DwtCopyFromClipboard to obtain the current next paste
data item from clipboard storage. Because the matching functions
DwtStartCopyFromClipboardand DwtEndCopyFromClipboard
comply with the ICCCM conventions, their use is recommended over
DwtCopyFromClipboard. Each of these functions is discussed in the
following sections.

8.8.1

Using DwtStartCopyFromClipboard and
DwtEndCopyFromClipboard
To indicate that the application is ready to start copying data from the
clipboard, use DwtStartCopyFromClipboard.
int Dwt StartCopyFromClipboard (display, window, time)
Display * display ;
Window window;
Time time;
display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

time

Specifies the times tamping of the event that triggered the
copy.

The DwtStartCopyFromClipboard function notifies the cut and paste
functions that the application is ready to start copying data from the
clipboard. DwtStartCopyFromClipboard locks the clipboard and
remains locked until you call DwtEndCopyFromClipboard.

8-12 Cut and Paste Functions

After calling DwtStartCopyFromClipboard, an application can make
multiple calls to DwtCopyFromClipboard requesting data in one or
several formats. You specify the format by setting the format_name
argument to DwtCopyFromClipboard. Each call to
DwtCopyFromClipboard in a specified format results in data being
incrementally copied from the clipboard until all data with the specified
format has been copied. When all data in a specified format has been
successfully copied, DwtCopyFromClipboard returns
ClipboardSuccess. When more data remains to be copied in the
specified format, DwtCopyFromClipboard returns
ClipboardTruncate. An application can copy data in as many formats
as desired before calling DwtEndCopyFromClipboard.
It is recommended that any calls to inquire routines needed by the application
be made between the call to DwtStartCopyFromClipboard and the
call to DwtEndCopyFromClipboard. That way, the application does
not need to call DwtClipboardLock and DwtClipboardUnlock.

To perform cut and paste operations between your application and an
application using the ICCCM clipboard selection mechanism, you must use
DwtStartCopyToClipboard and provide a timestamping value for time,
not a Current Time value. Use of the value Current Time for time may
cause the ICCCM interface to fail.
Applications do not need to use DwtStartCopyFromClipboard and
DwtEndCopyFromClipboard, in which case
DwtCopyFromClipboard works as documented. However, using these
two functions allows incremental copying from the clipboard and ensures
ICCCM compatibility.
This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

To indicate that the application is ready to start copying data from the
clipboard, use DwtEndCopyFromClipboard.

Cut and Paste Functions 8-13

int DwtEndCopyFromClipboard (display, window)
Display * display;
Window window;

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

The DwtEndCopyFromClipboard function unlocks the clipboard when
the application has copied all data from the clipboard. If the application calls
DwtStartCopyFromClipboard, it must call
DwtEndCopyFromClipboard. These two functions lock and unlock the
clipboard and allow the application to copy data from the clipboard
incrementally.
This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

8.8.2

Using DwtCopyFromClipboard
To obtain the current next paste data item from clipboard storage, use
DwtCopyFromClipboard.
int DwtCopyFromClipboard (display, window, format_name,

buffer, length,
num_bytes, private_id )

Display * display;
Window window;
char *format_name;
char * buffer;
unsigned long kng~;
unsigned long * num_bytes;
int * private_id;
8-14 Cut and Paste Functions

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

format_name

Specifies the name of a fonnat in which the data is stored on
the clipboard.

buffer

Specifies the buffer to which the application wants the
clipboard to copy the data.

length

Specifies the length of the application buffer.

num_bytes

Specifies the number of bytes of data copied into the
application buffer.

private_id

Specifies the private data stored with the data item by the
application that placed the data item on the clipboard. If the
application did not store private data with the data item, this
argument returns zero.

The DwtCopyFromClipboard function retrieves the current next-paste
item from clipboard storage.
DwtCopyFromClipboard returns a warning under the following

circumstances:
•

The data needs to be truncated because the buffer length is too short

•
•

The clipboard is locked
There is no data on the clipboard

This function returns one of these status return constants:
ClipboardSuccess

Cut and Paste Functions 8-15

ClipboardLocked

ClipboardTruncate

ClipboardNoData

The function failed because the clipboard
was locked by another application. The
application can continue to call the function
with the same parameters until the
clipboard is unlocked. Optionally, the
application can ask if the user wants to
keep trying or to give up on the operation.
If using DwtCopyFromClipboard
alone, the data returned is truncated because
the user did not provide a buffer that was
large enough to hold the data. If using
multiple calls to
DwtCopyFromClipboard in between
calls to
DwtStartCopyFromClipboardand
DwtEndCopyFromClipboard, more
data in the requested format remains to be
copied from the clipboard.
The function could not find data on the
clipboard corresponding to the format
requested. This could occur because: (1)
the clipboard is empty; (2) there is data on
the clipboard but not in the requested
format; and (3) the data in the requested
format was passed by name and is no
longer available.

8.9 Copying a Data Item to the Clipboard
To copy a data item to clipboard storage, use DwtCopyToClipboard.
int DwtCopyToClipboard (display, window, item_id,
format_name, buffer, length,
private_id , data_id)
Display * display;
Window window;
long item_id;
char *format_name;
char * buffer;
unsigned long length;
in t private_id ;
int * data_id;

display

Specifies a pointer to the Display structure that was
returned in a previous call to XOpenDisplay. For
information on XOpenDisplay and the Display

8-16 Cut and Paste Functions

structure, see the Guide to the Xlib Library: C Language
Binding.
window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

item id

Specifies the number assigned to this data item. This number
was returned by a previous call to
DwtBeginCopyToClipboard.

format_name

Specifies the name of the format in which the data item is
stored.

buffer

Specifies the buffer from which the clipboard copies the data.

length

Specifies the length of the data being copied to the clipboard.

private_id

Specifies the private data that the application wants to store
with the data item.

data id

Specifies an identifying number assigned to the data item that
uniquely identifies the data item and the format. This
argument is required only for data that is passed by name.

The DwtCopyToClipboard function copies a data item to clipboard
storage. The data item is not actually entered in the clipboard. data structure
until the call to DwtEndCopyToClipboard. Additional calls to
DwtCopyToClipboard before a call to DwtEndCopyToClipboard
add data item formats to the same data item or append data to an existing
format.
If the buffer argument is NULL, the data is considered passed by name. If
data passed by name is later needed by another application, the application
that owns the data receives a callback with a request for the data. The
application that owns the data must then transfer the data to the clipboard
with the DwtReCopyToClipboard function. When a data item that was
passed by name is deleted from the clipboard, the application that owns the
data receives a callback that states that the data is no longer needed.

For information on the callback function, see the callback argument
description for DwtBeginCopyToClipboard.
This function returns one of these status return constants:
ClipboardSuccess

The function is successful.

Cut and Paste Functions 8-17

ClipboardLocked

8.10 Placing Data in the Clipboard
To lock the clipboard, to place data in the clipboard data structure, and to
unlock the clipboard, use DwtEndCopyToClipboard.
int DwtEndCopyToClipboard (display, window, item_id)
Display * display;
Window window;
long item_id;

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

item id

Specifies the number assigned to this data item. This number
was returned by a previous call to
DwtBeginCopyToClipboard.

The DwtEndCopyToCl ipboard function locks the clipboard from access
by other applications, places data in the clipboard data structure, and unlocks
the clipboard. Data items copied to the clipboard by
DwtCopyToClipboard are not actually entered in the clipboard data
structure until the call to DwtEndCopyToClipboard.
This function returns one of these status return constants:
ClipboardSuccess

8-18 Cut and Paste Functions

The function is successful.

ClipboardLocked

8.11

The function failed because the clipboard
was locked by another application. The
application can continue.to call the function
with the same parameters until the
clipboard is unlocked. Optionally. the
application can ask if the user wants to
keep trying or to give up on the operation.

Returning the Number of Data Item Formats
To return the maximum length for all data item formats, use
DwtlnquireNextPasteCount.
int DwtlnquireNextPasteCount (display, window, count,
maxJormat_name_length)
Display * display;
Window window;
int * count ;
int * maxJormat_name_length;

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

count

Returns the number of data item formats available for the
next-paste item in the clipboard. If no formats are available,
this argument equals zero. The count includes the formats
that were passed by name.

maxJormat_name_length
Specifies the maximum length of all format names for the
next-paste item in the clipboard.
The DwtlnquireNextPasteCount function returns the number of data
item formats available for the next-paste item in the clipboard. This function
also returns the maximum name length for all formats in which the next-paste
item is stored.
This function returns one of these status return constants:
ClipboardSuccess

The function is successful.

Cut and Paste Functions 8-19

ClipboardLocked

ClipboardNoData

8.12 Returning a Specified Format Name
To obtain the format name for the next paste data item in the clipboard, use
DwtlnquireNextPasteFormat.
int DwtlnquireNextPasteFormat (display, window,
Display * display;
Window window;
int number;
char *format_name_buf;
unsigned long buffer_len;
unsigned long *copied_len;

number, format name buf,
buffer_len, copied_len")

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

number

Specifies the number of format names to be obtained. If this
number n is greater than the number of formats for the data
item, DwtlnquireNextPasteFormat returns a zero in
the copied_len argument.
format name buf
- Specifies the buffer that receives the format name.

8-20 Cut and Paste Functions

Specifies the number of bytes in the format name buffer.
Specifies the number of bytes in the string copied to the
buffer. If this argument equals zero, there is no nth format
for the next-paste item.
The DwtInquireNextPasteFormat function returns a specified format
name for the next-paste item in the clipboard. If the name must be truncated,
the function returns a warning status. This function returns one of these
status return constants:
ClipboardSuccess
ClipboardLocked

ClipboardTruncate

ClipboardNoData

The function is successful.
The function failed because the clipboard
was locked by another application. The
application can continue to call the function
with the same parameters until the
clipboard is unlocked. Optionally, the
application can ask if the user wants to
keep trying or to give up on the operation.
The data returned is truncated because the
user did not provide a buffer that was large
enough to hold the data.
Information could not be obtained from an
application using the ICCCM clipboard
selection mechanism. This return value
indicates that the data was not available in
the requested format.

8.13 Returning the Length of the Stored Data
To obtain the length of the data stored under a specified format, use
DwtInquireNextPasteLength.
int DwtInquireNextPasteLength (display, window,

format_name, length)
Display * display;
Window window;
char *format_name;
unsigned long * length;

display

Cut and Paste Functions 8-21

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

format_name

Specifies the name of the format for the next-paste item.

length

Specifies the length of the next data item in the specified
format. This argument equals zero if no data is found for the
specified format, or if there is no item on the clipboard.

The DwtlnquireNextPasteLength function returns the length of the
data stored under a specified format name for the next paste clipboard data
item.
If no data is found for the specified format, or if there is no item on the
clipboard, DwtlnquireNextPasteLength returns a value of zero.

Note
Any format passed by name is assumed to have the length passed
in a call to DwtCopyToClipboard, even though the data has
not yet been transferred to the clipboard in that format.
This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

ClipboardNoData

The function is successful.
The function failed because the clipboard
was locked by another application. The
application can continue to call the function
with the same parameters until the
clipboard is unlocked. Optionally, the
application can ask if the user wants to
keep trying or to give up on the operation.
Information could not be obtained from an
application using the ICCCM clipboard
selection mechanism. This return value
indicates that the data was not available in
the requested format.

8.14 Returning a List of Data ID/Private 10 Pairs
To obtain a format name's list of data ID or private ID pairs, use
DwtListPendingltems.

8-22 Cut and Paste Functions

int DwtListPendingltems (display, window, format_name,

item_list, count)

Display * display ;
Window window;
char *format_name;
DwtClipboardPendingList
unsigned long * count;

* item_list;

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

format name

Specifies a string that contains the name of the format for
which the list of data ID/private ID pairs is to be obtained.

item list

Specifies the address of the array of data ID/private ID pairs
for the specified format name. This argument is a type
DwtClipboardPendingList. The application is
responsible for freeing the memory provided by this function
for storing the list.

item count

Specifies the number of items returned in the list. If there is
no data for the specified format name, or if there is no item
on the clipboard, this argument equals zero.

The DwtListPendingltems function returns a list of data ID/private ID
pairs for a specified format name. For the purposes of this function, a data
item is considered pending if the application originally passed it by name, the
application has not yet copied the data, and the item has not been deleted
from the clipboard.
The application is responsible for freeing the memory provided by this
function to store the list.
This function is used by an application when exiting to determine if the data
that it passed by name should be sent to the clipboard.
This function returns one of these status return constants:
ClipboardSuccess

The function is successful.

Cut and Paste Functions 8-23

ClipboardLocked

8.15 Copying a Data Item Passed by Name
To copy a data item to the clipboard, use DwtReCopyToClipboard.
int DwtReCopyToClipboard (display, window, data_id,
Display * display;
Window window;
int data_id;
char * buffer;
unsigned long length;
int private_id;

buffer, length, private_id )

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

data id

Specifies an identifying number assigned to the data item that
uniquely identifies the data item and the format. This
number was assigned by DwtCopyToClipboard to the
data item.

buffer

Specifies the buffer from which the clipboard copies the data.

length

Specifies the number of bytes in the data item.

private_id

Specifies the private data that the application wants to store
with the data item.

The DwtReCopyToClipboard function copies the actual data for a data
item that was previously passed by name to the clipboard. Additional calls
to DwtReCopyToClipboard append new data to the existing data. This
function cannot be used to pass data by name.

8-24 Cut and Paste Functions

This function returns one of these status return constants:
ClipboardSuccess
ClipboardLocked

8.16 Deleting the Last Item Placed on the Clipboard
To delete the last item placed on the clipboard, use
DwtUndoCopyToClipboard.
int DwtUndoCopyToClipboard (display, window)
Display * display ;
Window window;

display

window

Specifies the window ID that relates the application window
to the clipboard. The same application instance should pass
the same window ID to each clipboard function that it calls.

The DwtUndoCopyToClipboard function deletes the last item placed on
the clipboard if the item was placed there by an application with the passed
display and window arguments. Any data item deleted from the clipboard by
the original call to DwtCopyToClipboard is restored. If the display or
window IDs do not match the last copied item, no action is taken and this
function has no effect.
This function returns one of these status return constants:
ClipboardSuccess

The function is successful.

Cut and Paste Functions 8-25

ClipboardLocked

8.17 Register Data Length for Non-ICCCM Formats
To register the data length for non-ICCCM formats, use
DwtClipboardRegisterFormat.
int DwtClipboardRegisterFormat (display, format_name,
Display * display ;
char * format_name;
unsigned long format_length;

format_length)

display

format name

Specifies a name string for the format. See the table of Data
Format Names for the formats defined by ICCCM
conventions.

format_length Specifies the format length in bits: 8, 16, or 32.
The DwtClipboardRegisterFormat function allows an application to
register the data length for formats not specified by the ICCCM conventions.
Failure to register the length of the data results in applications being
incompatible across platforms that have different byte-swapping orders.
See Table 8-1 for the formats defined by the ICCCM conventions.
This function returns one of these status return constants:
ClipboardSuccess

8-26 Cut and Paste Functions

The function is successful.

ClipboardLocked

ClipboardBadFormat

ClipboardFail

Cut and Paste Functions 8-27

Compound String Functions

The XUI Toolkit provides a set of compound string functions that enable the
creation and manipulation of compound strings and font lists. A compound
string is a sequence of segments. Each segment consists of a natural
language identifier, a text direction identifier, rendition information, a
character set identifier, and a counted text string.
A font list is an array of font structures indexed by the character set
identifier. A character set identifier is a constant from the file
/usr / include/ cda def. h. This chapter discusses the compound
string functions you can-use to:

9.1

•

Create a font list and font list entries

•

Create compound strings

•

Compare and manipulate compound strings

•

Free a compound string context structure

Creating a Font List and Font List Entries
The functions discussed in this section allow you to create a new font list and
to add entries to this list.
To create a new font list, use DwtCreateFontList.
DwtFontList DwtCreateFontList (font, charset)
XFontStruct *font;
long charset;

font

Specifies a pointer to a font structure for which the new font
list is generated.

charset

Specifies the character set identifier for the font. Values for
this argument can be found in the required file
/usr/include/cda def.h.

The DwtCreateFontList function creates a new font list for the font
and character set. It also allocates the space for the font list. The end of the
font list is marked by an element whose character set value is -1.
This function returns a new font list. However, it returns NULL if the font
specified in font is NULL.

To add an entry to a font list, use DwtAddFontList.
DwtFontList DwtAddFontList (list, font, charset)
DwtFontLi st list;
XFontStruct *font;
long charset;

list

Specifies a pointer to the font list to which an entry will be
added.

font

Specifies a pointer to the font structure to be added to the
list.

charset

Specifies the character set identifier for the font. Values for
this argument can be found in the required file
/usr/include/cda_def.h.

The DwtAddFontList function adds an entry to a font list.
This function returns the new font list.

9.2 Creating a Compound String
The functions discussed in this section allow you to create a compound string
and to create a compound-string for the LATINI character set.
To create a compound-string, use DwtCSString.
DwtCompString DwtCSString (text, charset, direction_r_to_l,
char * text ;
unsigned long charset;
char direction r to l;
unsigned lo~g language;
DwtRendMask rend;

language, rend)

text

Specifies the text string to be converted to a compoundstring.

charset

Specifies the character set for the compound-string. Values
for this argument can be found in the required file
/usr/include/cda def.h.

direction _r_to_lSpecifies the direction in which the text is drawn and wraps.
You can pass DwtDirectionLeftDown (text is drawn
from left to right and wraps down);
DwtDirectionRightUp (text is drawn from left to right
and wraps up); DwtDirectionLeftDown (text is drawn
from right to left and wraps down); or
DwtDirectionLeftUp (text is drawn from right to left
and wraps up).
9-2 Compound String Functions

language

Included for future use.

rend

Included for future use.

The DwtCSString function creates a compound-string from information in
the argument list. Space for the resulting string is allocated within the
function. After using this function, you should free the space by calling
XtFree.
This function returns the resulting compound-string. However, it returns a
NULL pointer if the input string is NULL.
To create a compound-string using a simpler interface than the one used for
DwtCSString, call DwtString.
DwtCornpString DwtString (text, charset, direction_r_to_l)
char * text ;
unsigned long charset;
char direction_r_to_I;

text

Specifies the text string to be converted to a compoundstring.

charset

Specifies the character set for the compound-string. Values
for this argument can be found in the required file
/usr/include/cda_def.h.

direction r to ISpecifies the direction in which the text is drawn and wraps.
- - - You can pass DwtDirectionLeftDown (text is drawn
from left to right and wraps down);
DwtDirectionRightUp (text is drawn from left to right
and wraps up); DwtDirectionLeftDown (text is drawn
from right to left and wraps down); or
DwtDirectionLeftUp (text is drawn from right to left
and wraps up).

The DwtString function creates a compound-string from information in
the argument list. It has a simpler interface than the one used for
DwtCSString.
DwtString assumes the following default values:

•

For language the default is DwtLanguageNotSpecified.

•

For rend the default is DwtRendMaskNone.

The space for the resulting compound-string is allocated within the function.
After using this function, you should free this space by calling XtFree.
This function returns the resulting compound-string. However, it returns a
NULL pointer if the text is NULL.
To create a compound-string for the LATINI character set, use
DwtLatinlString.
Compound String Functions 9-3

DwtCompString DwtLatinlString (text)
char * text ;

text

Specifies the text string to be converted to a compoundstring.

The DwtLatinlString function creates a compound-string and is
provided for those application programmers who do not need to mix
compound-strings containing different character sets and directions.
DwtLatinlString assumes the character encoding of the text to be
ISO_LATINI and the writing direction to be from left to right.
This function returns the resulting compound-string. It has the following
default values:
•

For charset the default is CDA$K_ISO_LATIN1.

•

For direction r to I the default is False (text is drawn from left to
right).
- - -

•

For language the default is DwtLanguageNotSpecified.

•

For rend the default is DwtRendMaskNone.

9.3 Comparing and Manipulating Compound Strings
The functions discussed in this chapter allow your application to:

9.3.1

•

Determine if two strings are identical

•

Determine if a compound-string is empty

•

Append a copy of a string to another string

•

Copy a string to the output string

•

Return number of bytes in string 1

•

Work with segments

Determining If Two Compound Strings Are Identical
To determine if two compound-strings are identical, use DwtCSbytecmp.
int DwtCSbytecmp (compound string1, compound string2)
DwtCompString compound_string1, compound_string2;

compound string1
Specifies a compound-string to be compared with
compound_string2.

9-4 Compound String Functions

compound string2
Specifies a compound-string to be compared with
compound_string1.

The DwtCSbytecmp function returns zero if compound string1 and
compound_string2 are exactly the same (byte to byte). It returns one if they
are not the same.

9.3.2

Determining If a Compound String Is Empty
To determine if a compound-string is empty, use DwtCSempty.
int DwtCSempty (compound string)
DwtCompString compound_string;

compound_ stringSpecifies the compound-string.

The DwtCSempty function determines if the compound-string contains any
text segments. DwtCSempty returns True if all text segments in the
compound-string are empty. Otherwise, it returns False.

9.3.3

Appending a Copy of a String to Another String
To append a copy of a compound-string to another compound-string, use
DwtCStrcat or DwtCStrncat.
DwtCompString DwtCStrcat (compound_string1,
compound string2)
DwtCompString compound_string1, -compound_string2;
DwtCompString DwtCStrncat (compound_string1,
compound_ string2 ,
num chars)
DwtCompString compound_string1 ,
compound_string2 ;
int num_chars;

compound_string1
Specifies a compound-string to which a copy of
compound_string2 is appended.
compound_ string2
Specifies a compound-string that is appended to the end of
compound_ string1.
num chars

Specifies the number of characters to be appended to the
specified compound-string. If num_chars is less than the
length of compound_ string2, the resulting string will not be a
valid compound-string.

Compound String Functions 9-5

The DwtCStrcat function appends compound_string2 to the end of
compound_string] and returns the resulting string. The original strings are
preserved. The space for the resulting compound-string is allocated within
the function. After using this function, you should free this space by calling
XtFree.
The DwtCStrncat function appends no more than the number of
characters specified in num_chars, which includes tag and length sections of
the compound-string.
These functions return a pointer to the resulting compound-string.

9.3.4

Copying a String to the Output String
To copy a compound-string to the output string, use DwtCStrcpy or
DwtCStrncpy.
DwtCompString DwtCStrcpy (compound_string])
DwtCompString compound_string];
DwtCompString DwtCStrncpy (compound_string], num_chars)
DwtCompString compound_string];
int num_chars;

compound string]
Specifies a compound-string to be copied to the output string.
num chars

Specifies the number of characters to be copied. If
num_chars is less than the length of compound_string], the
resulting string will not be a valid compound-string.

The DwtCStrcpy function copies the string in compound_string].
The DwtCStrncpy function copies exactly the number of characters
specified in num_chars, including the headers and trailers.
The space for the resulting compound-string is allocated with these functions.
After using these functions, you should free this space by calling XtFree.
These functions return a pointer to the resulting compound-string.

9.3.5

Returning the Number of Bytes In String1
To obtain the length of compound_string], use DwtCStrlen.

9-6 Compound String Functions

int DwtCStr len (compound_string] )
DwtCompString compound_string];

compound_string]
Specifies a compound-string whose length is determined.
The DwtCStrlen function returns the number of bytes in
compound_string1, including compound-string terminators for headers and
trailers. If the compound-string has an invalid stucture, zero is returned.

9.3.6

Working with Segments
The functions discussed in this section allow you to obtain information about
the next segment, to obtain the initialized context of the compound string,
and to initialize a compound string context structure. To obtain information
about the next segment in a compound string, use DwtGetNextSegment.
int DwtGetNextSegment (context, text return,
charset_return ,- direction_r_to_I_return,
lang_return, rend_return)
DwtCompStringContext * context;
char * text_return;
long * charset_return;
int * direction_r_to_I_return;
long * lang_return;
long * rend_return;

context

Specifies the context for the call to
Dwtlni tGetSegment. You initialize the context by
calling Dwtlni tGetSegment, and it gets incremented
each time you call DwtGetNextSegment.

text return

Returns the text in the next segment.

charset return Returns the character set in the next segment. Values for this
argument can be found in the required file
/usr/include/cda_def.h.
direction r to I return
- Returns the character direction value.
lang_return

For future use.

rend return

For future use.

The DwtGetNextSegment function obtains information about the next
segment of the compound-string as determined by the context. The space for
the resulting compound-string is allocated with this function. After using
this function, you should free this space by calling XtFree.

Compound String Functions 9-7

This function returns one of these status return constants:
The context is at the end of the compoundstring.
The context is not valid.
Nonnal completion.

DwtEndCS
DwtFail
DwtSuccess

To obtain the initialized context of the compound string, use
Dwt Ini tGetSegment ..
int Dwt Ini tGetSegment (context 1 compound_string)
DwtCompStringContext * context;
DwtCompString compound_string;

context

Specifies a context to be filled by this function. You should
have previously allocated this context.

compound_stringSpecifies the compound-string.

The DwtlnitGetSegment function returns the initialized context
associated with the compound-string you specified (compound_string). You
must use this returned context in a call to DwtGetNextSegment.
Note that the performance of DwtlnitGetSegment (used in conjunction
with DwtGetNextSegment to fetch multiple segments from a
compound-string) has degraded from Version 1.0 of the toolkit.
A new function, DwtStringlnitContext, not only provides better
performance, it also creates the context structure that you must allocate
separately when using DwtlnitGetSegment. To improve performance,
convert calls from DwtlnitGetSegment to
DwtStringlnitContext, and use DwtStringFreeContext to free
the context structure when you are finished with it.
This function returns one of these status return constants:
DwtSuccess
DwtEndCS
DwtFail

N onnal completion.
The string specified in compound_string is
NULL.
The string specified in compound_string is
not a compound-string.

To initialize a compound string context structure, use
DwtStringlnitContext.

9-8 Compound String Functions

Boolean DwtStringIni tContext (context, compound_string)
DwtCompStringContext context;
DwtCompString compound_string;

context

Specifies the compound~string context structure initialized by
DwtStringInitContext.

compound_string Specifies the compound~string.
The DwtStringIni tContext function initializes a compound-string
context structure. The context structure is needed for calling
DwtGetNextSegment. For performance reasons,
DwtStringInitContext is preferred over DwtInitGetSegment.
After fetching the necessary segments using DwtGetNextSegment, call
DwtStringFreeContext to free the context structure.
This function returns one of these status return constants:
True
False

The compound~string context structure has
been successfully initialized.
The compound~string context structure has
not been successfully initialized.

9.4 Freeing a Compound String Context Structure
To free a compound string context structure, use
DwtStringFreeContext.
void DwtStringFreeContext (context)
DwtCompStringContext * context;

context

Specifies the compound~string context structure initialized by
DwtStringInitContext.

The DwtStringFreeContext function frees the compound~string
context structure returned by DwtStringIni tContext. When your
application has finished with the context, it should call
DwtStringFreeContext.

Compound String Functions 9-9

Convenience Functions

This chapter discusses the following types of convenience functions:
•

Functions that allow you to display messages

•

A function that allows you to write upward-compatible applications and
widgets

•

A function that allows applications to simulate push button activation

•

A function that returns user data associated with the widget

10.1

Functions That Display Messages
The message functions allow messages to be formatted using the $FAO
utility and to be displayed in a message box. Messages such as those from
the operating system appear ina message box. The messages themselves are
either stored in a VMS message file or supplied by the application as
compound-strings.
The message box can be either modal or modeless. The title bar identifies
the message box with the title Message and contains a push-to-back icon.
The message box contains a message box icon in the upper-left comer, an
Acknow ledged push button on the bottom, and the text of the message in the
middle. The lines of the message are separated by <CR><LF> pairs or "!I"
in $FAO. Multiple messages are separated by blank lines.
The user clicks on the Acknowledged push button to erase the message. To
receive help on the message, the user presses the Help key while the message
box has input focus.
In addition to the standard $FAO system service flags, the compound string
message function (DwtDisplayCSMessage) accepts the flag" !CS".
When used, this flag accepts a compound-string itself.

ULTRIX applications can make use of the FAO string substitution utility.
Messages defined in the Resource Manager (DRM) database can be supplied
to the appropriate message function to be formatted and displayed.
The following sections discuss the functions you can use to:
•
•

Accept and display a VMS message
Display a compound-string message

10.1.1

Accepting and Displaying a VMS Message
To accept and display a VMS message, use DwtDisplayVmsMessage.
Widget DwtDisplayVmsMessage (parent_widget, name,

defaultyosition , x, y,
style, message_vector,
widget_id, convertyroc,
ok_callback, help_callback)
Widget parent_widget;
char * name ;
int defaultyosition ;
int x, y;
int style;
int * message_vector;
Widget * widget_id;
in t ( *convertyroc) ();
DwtCallbackPtr ok callback;
DwtCallbackptr help callback;

parent_widget Specifies the parent widget ID.
name
Specifies the name of the created widget.
defaultyositionSpecifies a boolean value that, when True, indicates that
DwtNx and DwtNy are to be ignored forcing the widget to
be centered in the parent window.
x
Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window.
y
Specifies, in pixels, the placement of the upper left corner of
the widget window relative to the inner upper left comer of
the parent window.
style
Specifies the style of the message box widget. You can pass
DwtModal (modal) or DwtModeless (modeless).
message_vector Specifies the message argument vector identifying the
message identifier and associated information. This
argument is identical to the VMS $PUTMSG system service.
The first longword contains the number of longwords in the
message blocks to follow. The first longword in each
message block contains a pointer to the VMS message
identifier. Message identifiers are passed by value.

10-2 Convenience Functions

If the message is user-supplied, the next word consists of the
$FAO parameter count. The final n longwords in the
message block are the $FAO parameters.

widget_id

This argument contains the widget ID of an already-existing
message box widget. If this argument is nonzero, a new
message box is not created. An XtSetValues will be
performed on this widget to change the text of the message
to match this new message. This is an input/output
argument. That is, the function fills in widget_id after you
call it.

convertyroc

Specifies a pointer to a function that is executed after the
message is formatted but before it is displayed. A pointer to
the formatted string is passed to the function as a parameter.
This parameter is a NULL-terminated character string.

ok callback

Specifies the callback function or functions called when the
user clicks on the Acknowledged push button. For this
callback, the reason is Dwt CRY e s .

help_callback Specifies the callback function or functions called when a
help request is made.
The DwtDisplayVrnsMessage function accepts standard VMS message
vectors (as defined by the $PUTMSG system service), retrieves the messages,
formats them, and creates a message box in which to display the message.
Upon completion, DwtDisplayVrnsMessage returns to the calling
program the ID of the created message box widget.
This parameter is a NULL-terminated character string.

10.1.2

Displaying a Compound String Message
To display a compound-string message, use DwtDisplayCSMessage.
Widget DwtDisplayCSMessage (parent_widget, name,

defaultyosition , x, y,
style, message vector,
widget_id convertyroc ,
ok_callback, help_callback)
Widget parent_widget;
char * name ;
int defaultyosition ;
int x, y;
int style;
in t * message vector;
Widget * widget ;
int (*convertyroc) ();
DwtCallbackPtr ok_callback;
DwtCallbackPtr help_callback;
Convenience Functions 10-3

parent_widget Specifies the parent widget ID.
name

Specifies the name of the created widget.

de[aultyositionSpecifies a boolean value that, when True, indicates that
DwtNx and DwtNy are to be ignored forcing the widget to
be centered in the parent window.

Specifies the placement, in pixels, of the left side of the
widget window relative to the inner upper left comer of the
parent window.

Specifies, in pixels, the placement of the upper left comer of
the widget window relative to the inner upper left comer of
the parent window.

style

Specifies the style of the message box widget. You can pass
DwtModal (modal) or DwtModeless (modeless).

message_vector Specifies the message argument vector identifying the
message identifier and associated information.

The first longword contains the number of longwords in the
message blocks to follow. The first longword in each
message block contains a pointer to the compound-string.
The next word consists of the FAO parameter count. The
final n longwords in the message block are the FAO
parameters.
widget_id

convertyroc

Specifies a pointer to a function that is executed after the
message is formatted but before it is displayed.
A pointer to the formatted compound-string is passed to the
function as a parameter. This parameter is a NULLterminated character string.

ok callback

Specifies the callback function or functions called when the
user clicks on the Acknowledged push button. For this
callback, the reason is Dwt CRY e s.

help_callback Specifies the callback function or functions called when a
help request is made.

10-4 Convenience Functions

The DwtDisplayCSMessage function accepts an array of compoundstrings, formats them, and creates a message box. Upon completion,
DwtDisplayCSMessage returns to the calling program the ID of the
created message box widget.
If the function returns a zero, the message is not appended to the messages to
be displayed.

10.2 Function That Allows Writing Upward-Compatible
Applications and Widgets
The widget instance records defined by the XUI Toolkit are not inherently
upward compatible. That is, applications and widgets built outside of the
toolkit cannot use hard-coded offsets into the widget instance records and
expect to run without recompilation as subsequent releases of the XUI
Toolkit occur. A method of writing upward-compatible applications and
widgets has been defined.
To allocate offset records, use DwtResol vePartOffsets.
void DwtResol vePartOffsets (widget_class, offset)
WidgetClass widget class;
DwtOffsetPtr *offs~;

widget_class

Specifies the widget class pointer for the created widget.

offset

Specifies the offset record.

Applications and widgets must never read or write another widget's fields
directly. There is one exception to this: as geometry manager, a widget's
parent may read and write the widget's geometry fields. A widget not
guaranteed to be recompiled with the intrinsics must use an "offset record"
to access the field within its instance record.
The use of offset records requires one extra global variable per widget class.
The variable consists of a pointer to an array of offsets into the widget record
for each part of the widget structure. The DwtResolvePartOffsets
function allocates the offset records needed by an application to guarantee
upward-compatible applications and widgets. These offset records are used
by the widget to access all of the widget's variables.
A widget needs to take the following steps:
•

Instead of creating a resource list, the widget creates an offset resource
list. To help you accomplish this, use the DwtPartResource
structure and the DwtPartOffset macro. The
DwtPartResource data structure looks just like a resource list, but
instead of having one integer for its offset, it has two shorts. This gets
put into the class record as if it were a normal resource list. Instead of
using XtOffset for the offset, it uses DwtPa:r;tOffset.
Convenience Functions 10-5

•

Instead of putting the widget size in the class record, the widget puts
the widget part in the same field.

•

Instead of putting XtVersion in the class record, the widget puts
XtVersionDontCheck in the class record.

•

The widget defines a variable to point to the offset record. This can be
part of the widget's class record or a separate global variable.

•

In class initialization, the widget calls DwtRe sol veP art 0 f f set s,
passing it the offset address and the class record. This does several
things:
Adds the superclass (which, by definition, has already been
initialized) size field to the part size field.
Allocates an array based upon the number of superclasses.
Fills in the offsets of all the widget parts with the appropriate
values, detennined by examining the size fields of all superclass
records.
Uses the part offset array to modify the offset entries in the
resource list to be real offsets, in place.

•

Instead of accessing fields directly, the widget must always go through
the offset table. You will probably define macros for each field to make
this easier. Assume an integer field "xyz":
#define BarXyz (w) (* (int *) ( «char *) w) + offset [Barlndex] + \
XtOffset(BarPart,xyz»)

The DwtField macro helps you access these fields. Because the
DwtPartOffset and DwtField macros concatenate arguments,
you must ensure there is no space before or after the part argument. For
example, the following do not work because of the space before or after
the part (Label) argument:
DwtField(w, offset, Label, text, char *)
DwtPartOffset( Label, text).

Therefore, you must not have any spaces before or after the part (Label)
argument, as illustrated here:
DwtField(w, offset,Label, text, char *)

10.3 Function That Allows Applications to Simulate
Push Button Activation
To allow your application to simulate push button activations, use
DwtActivateWidget.

10-6 Convenience Functions

void DwtActivateWidget (widget)
Widget widget;

widget

Specifies a pointer to the widget data structure.

The DwtActi vateWidget function allows the application to simulate
push button activation. DwtActi vateWidget generates the same
highlighting and callbacks that would occur if the user clicks on a push
button. For example, an application might contain functions that a user could
choose either by selecting a menu option or by activating a push button. If
the user selected the menu option, the application could activate the
corresponding push button to maintain a consistent user interface. Only push
buttons are currently supported by DwtActi vateWidget.

10.4 Function That Returns User Data Associated with
the Widget
To return the user data associated with the widget, use DwtGetUserData.
char

widget

* DwtGetUserData (widget)
Widget widget;
Specifies a pointer to the widget data structure.

The DwtGetUserData function returns any private user data associated
with the widget. The returned data is not interpreted by the toolkit.

Convenience Functions 10-7

Widget Attributes

This appendix provides tables that list the attributes supported by each
widget. Each table provides the attribute name, data type, and default. For
your convenience, the widgets are listed in alphabetical order.

A.1

Attached Dialog Box and Attached Dialog Box PopUp Widgets
Table A-1: Attributes Inherited by the Attached Dialog Box and
Attached Dialog Box Pop-Up Widgets
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry .
manager
Detennined by the geometry
manager
Widget-specific
Widget-specific
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged

XtTranslations
int
XtTranslations
Boolean

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True

Table A-1:

(continued)

Attribute Name

Data Type

Default

DwtNscreen
DwtNdestroyCallback

Screen *
DwtCallbackptr

The parent screen

DwtNadbTopAttachment

DwtAttachmentType

DwtNadbBottomAttachment

DwtAttachmentType

DwtNadbLeftAttachment

DwtAttachmentType

DwtNadbRightAttachment

DwtAttachmentType

DwtAttachAdb if
DwtNrubberPositioningis
False
DwtAttachSelf if
DwtNrubberPositioningis
True
The default is DwtAttachNone
li DwtNrubberPositioning
is False.
The default is DwtAttachSelf
li DwtNrubberPositioning
is True.
The default is DwtAttachAdb
li DwtNrubberPositioning
is False.
The default is DwtAttachSelf
li DwtNrubberPositioning
is True.
The default is DwtAttachNone
li DwtNrubberPositioning
is False.
The default is DwtAttachSelf
li DwtNrubberPositioning
is True.

DwtNadbTopWidget
DwtNadbBottomWidget
DwtNadbLeftWidget
DwtNadbRightWidget
DwtNadbTopPosition
DwtNadbBottomPosition
DwtNadbLeftPosition
DwtNadbRightPosition
DwtNadbTopOffset

Widget
Widget
Widget
Widget
int
int
int
int
int

NULL

Constraint Attributes

A-2 Widget Attributes

NULL
NULL
NULL
NULL
Zero
Zero
Zero
Zero
The value specified with
DwtNdefaultVerticalOffsE
However, if
DwtNadbTopAttachmentis
DwtAttachPosi tion or
DwtAttachSelf, the default is
one-half the value specified with
DwtNdefaultVerticalOffsE

Table A-1:

(continued)

Attribute Name

Data Type

Default

DwtNadbBottomOffset

int

DwtNadbLeftOffset

int

DwtNadbRightOffset

int

DwtNresizable

Boolean

The default is the value specified
with
DwtNdefaultVerticalOffset.
However, if
DwtNadbBottomAttachment
is DwtAttachPosition or
DwtAttachSelf, the default is
one-half the value specified with
DwtNdefaultVerticalOffset.
The default is the value specified
with
DwtNdefaultHorizontalOffset.
However, if
DwtNadbLeftAttachmentis
DwtAttachPosition or
DwtAttachSelf, the default is
one-half the value of
DwtNdefaultHorizontalOffset.
The value specified with
DwtNdefaultHorizontalOffset.
However, if
DwtNadbRightAttachment
is DwtAttachPosition or
DwtAttachSelf, the default is
one-half the value specified with
DwtNdefaultHorizontalOffset.
True

Dialog Attributes

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNstyle

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char
unsigned char

DwtNfocusCallback
DwtNtextMergeTranslations

DwtCallbackPtr
XtTranslations

Default foreground color
Default foreground color
NULL
NULL

The default XUI Toolkit font
NULL

DwtDirectionRightDown
DwtFontUnits
For DwtDialogBoxCreate,
the default is DwtWorkarea.
For
DwtDialogBoxPopupCreate,
the default is DwtModeless.
NULL
NULL

Widget Attributes A-3

Table A-1 :

(continued)

Attribute Name

Data Type

Default

DwtNmarginWidth

Dimension

DwtNmarginHeight

Dimension

DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNgrabKeySyms

Boolean
Boolean
unsigned char
KeySym

DwtNgrabMergeTranslations

XtTranslations

For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreat
the default is 3 pixels.
For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreat
the default is 3 pixels.
False
True
DwtResizeGrowOnly
The default array contains the Tl
key symbol.
The default syntax is:
"-Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSNEXTO\J
Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSPREVO":

Table A-2: Widget-Specific Attributes for the Attached Dialog
Box and Attached Dialog Box Pop-Up Widgets
Attribute Name

Data Type

Default

DwtNdefaultHorizontalOffset
DwtNdefaultVerticalOffset
DwtNrubberPositioning
DwtNfractionBase

int
int
Boolean
int

Zero
Zero
False
100

A-4 Widget Attributes

A.2 Caution Box Widget
Table A-3: Attributes Inherited by the Caution Box Widget
Attribute Name

Data Type

Default

DwtNx

position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackptr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char
DwtCallbackptr
DwtCallbackPtr
DwtCallbackptr

Default foreground color
Default foreground color

NULL
NULL
The default XUI Toolkit font

NULL

Widget name
DwtModal

NULL
NULL
NULL
Widget Attributes A-5

Table A-3:

(continued)

Attribute Name

Data Type

Default

DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNtakeFocus

NOT SUPPORTED
Dimension
Dimension
Boolean
NOT SUPPORTED
unsigned char
Boolean

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
NOT SUPPORTED
NOT SUPPORTED

12 pixels
10 pixels
False
DwtResizeShrinkWrap
True for modal dialog box
F a Is e for modeless dialog box
True (that is, no window
manager resize button)
True

Table A-4: Widget-Specific Attributes for the Caution Box
Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNyesLabel
DwtNnoLabel
DwtNcancelLabel
DwtNdefaultPushbutton
DwtNyesCallback
DwtNnoCallback
DwtNcancelCallback

DwtCompString
DwtCompString
DwtCompString
DwtCompString
unsigned char
DwtCallbackptr
DwtCallbackptr
DwtCallbackPtr

Widget name
"Yes"
"No"
"Cancel"
DwtYesButton
NULL
NULL
NULL

A-6 Widget Attributes

A.3 Color Mix Widget
Table A-5: Attributes Inherited by the Color Mix Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Dialog Box Pop· Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback
DwtNunits
DwtNstyle
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char
DwtCallbackptr
XtTranslations
Dimension

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL
DwtFontUnits
DwtModeless
NULL
NULL
10 pixels

Attribute Name
Core Attributes

Widget Attributes A-7

Table A-5:

(continued)

Attribute Name

Data Type

Default

DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNnoResize
DwtNtitle
DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

Dimension
Boolean
Boolean
unsigned char
Boolean
DwtCompString
DwtCallbackptr
DwtCallbackPtr
Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton
DwtNgrabKeySyms

Boolean
Widget
Widget
KeySym

DwtNgrabMergeTranslations

xtTranslations

10 pixels
False
True
DwtResizeShrinkWrap
True
"Color Mixing"
NULL
NULL
True for modal dialog box
False for modeless dialog box
False
NULL
NULL
The default array contains the Ta
key symbol.
The default syntax is:
"-Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSNEXTO\r
Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSPREVO";

Table A-6: Widget-Specific Attributes for the Color Mix Widget
Attribute Name

Data Type

Default

DwtNmainLabel
DwtNdisplayLabel
DwtNmixerLabel
DwtNorigRedValue
DwtNorigGreenValue
DwtNorigBlueValue
DwtNnewRedValue

DwtCompString
DwtCompString
DwtCompString
unsigned short
unsigned short
unsigned short
unsigned short

NULL
NULL
NULL
Zero
Zero
Zero
Zero, unless
DwtNmatchColors is True,
in which case
DwtNnewRedValue is set to
match DwtNorigRedValue
whenever the widget is created
and mapped.

A-8 Widget Attributes

Table A-6:

(continued)

Attribute Name

Data Type

Default

DwtNnewGreenValue

unsigned short

DwtNnewBlueValue

unsigned short

DwtNdisplayWindow

Widget

DwtNsetNewColorProc

char *

DwtNmixerWindow

Widget

DwtNworkWindow
DwtNokLabel
DwtNapplyLabel
DwtNresetLabel
DwtNcancelLabel
DwtNokCallback
DwtNapplyCallback
DwtNcancelCallback
DwtNmatchColors

Widget
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCallbackptr
DwtCallbackptr
Boolean

DwtNresize

unsigned short

DwtNbackGreenValue

unsigned short

DwtNbackBlueValue

unsigned short

Zero, unless
DwtNmatchColors is True,
in which case
DwtNnewGreenVal ue is set to
match DwtNorigGreenValue
whenever the widget is created
and mapped.
Zero, unless
DwtNmatchColors is True,
in which case
DwtNnewBlueValue is set to
match DwtNorigBlueValue
whenever the widget is created
and mapped.
The color mixing widget display
subwidget
The function used by the color
mixing widget to update the new
color values displayed in the color
display subwidget.
The color mixing widget's RGB
color mixer subwidget
NULL
"OK"
"Apply"
"Reset"
"Cancel"
NULL
NULL
NULL
True
This attribute can be set only if
the default color display widget is
used.
Gray (32767)
This attribute can be set only if
the default color display widget is
used.
Gray (32767)
This attribute can be set only if
the default color display widget is
used.
Gray (32767)
This attribute can be set only if
the default color display widget is
used.

Widget Attributes A-9

Table A-6:

(continued)

Attribute' Name

Data Type

Default

DwtNdisplayColWinWidth

Dimension

DwtNdisplayColWinHeight

Dimension

DwtNdispWinMargin

Dimension

DwtNsliderLabel

DwtCompString

DwtNvalueLabel

DwtCompString

DwtNredLabel

DwtCompString

DwtNgreenLabel

DwtCompString

DwtNblueLabel

DwtCompString

80 pixels
This attribute can be set only if
the default color display widget is
used.
80 pixels
This attribute can be set only if
the default color display widget is
used.
20 pixels
This attribute can be set only if
the default color display widget is
used.
"Percentage"
This attribute can be set only if
the default color mix tool widget
is used.
"Value"
This attribute can be set only if
the default color mix tool widget
is used.
"Red"
This attribute can be set only if
the default color mix tool widget
is used.
"Green"
This attribute can be set only if
the default color mix tool widget
is used.
"Blue"
This attribute can be set only if
the default color mix tool widget
is used.

A-10 Widget Attributes

A.4 Command Window Widget
Table A-7: Attributes Inherited by the Command Window Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Determined by the geometry
manager
Determined by the geometry
manager
zero
zero
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Core Attributes

Dialog Pop-Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNtitle
DwtNstyle

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackptr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char

Default foreground color
Default foreground color
NULL
NULL
The default XUI Toolkit font
NULL

Widget name
DwtModal

Widget Attributes A-11

Table A-7:

(continued)

Attribute Name

Data Type

Default

DwtNmapCallback
DwtNunmapCallback
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition

DwtCallbackPtr
DwtCallbackPtr
DwtCallbackptr
NOT SUPPORTED
Dimension
Dimension
Boolean

NULL
NULL
NULL

DwtNchildOverlap
DwtNresize
DwtNtakeFocus

NOT SUPPORTED
NOT SUPPORTED
Boolean

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton
DwtNcancelButton

Boolean
NOT SUPPORTED
Widget
NOT SUPPORTED

12 pixels
10 pixels
True
This causes the command wind(
to be positioned in the bottom
left-hand comer of the parent
widget.

True for modal dialog box
False for modeless dialog bm
True (that is, no window
manager resize button)
True

NULL

Table A-8: Widget-Specific Attributes for the Command Window
Widget
Attribute Name

Data Type

Default

DwtNvalue
DwtNprompt
DwtNlines
DwtNhistory
DwtNcommandEnteredCallback
DwtNvalueChangedCallback
DwtNtTranslation

char *
DwtCompString
short
char *
DwtCallbackPtr
DwtCallbackptr
XtTranslations

NULL
">"
Two lines

A-12 Widget Attributes

NULL
NULL
NULL

A.S Compound String Text Widget
Table A-9: Attributes Inherited by the Compound String Text
Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Set as large as necessary to
display the DwtNrows and
DwtNcols with the specified
DwtNmarginWidth and
DwtNmarginHeight
Set as large as necessary to
display the DwtNcols and
DwtNrows with the specified
DwtNmarginHeightmd
DwtNmarginWidth
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive md
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Widget Attributes A-13

Table A-10: Widget-Specific Attributes for the Compound String
Text Widget
Attribute Name

Data Type

Default

Dimension
Dimension
Dimension
Dimension
DwtTextPosition
Boolean
Boolean
Boolean
Boolean
char *
Boolean
int
DwtCallbackPtr
DwtCallbackptr
DwtCallbackPtr
DwtCallbackPtr
Boolean
Boolean
int
Pixel

2 pixels
Two pixels
20 characters
1 character
Zero
False
False
True
True

DwtNfont

DwtFontList

DwtNblinkRate
DwtNscrollLeftSide
DwtNhalfBorder
DwtNpendingDelete
DwtNdirectionRToL
DwtNtextPath
DwtNeditingPath
DwtNbidirectionalCursor
DwtNnofontCallback

int
Boolean
Boolean
Boolean
unsigned char
int
int
Boolean
DwtCallbackPtr

A-14 Widget Attributes

True
2**31-1
NULL
NULL
NULL
NULL
True
True
Zero
The current server's default
foreground
The current server's
DwtFontList
500 milliseconds
False
True
True
DwtDirectionRightDow
Left to right
Left to right
False
NULL

A.6 Dialog Box and Pop-Up Dialog Box Widgets
Table A-11: Attributes Inherited by the Dialog Box and Pop-Up
Dialog Box Widgets
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Determined by the geometry
manager
Determined by the geometry
manager
Set as large as necessary to hold
all child widgets
Set as large as necessary to hold
all child widgets
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensi ti ve and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Core Attributes

Table A-12: Widget-Specific Attributes for the Dialog Box and
Pop-Up Dialog Box Widgets
Attribute Name

Data Type

Default

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap

Pixel
Pixel
Pixmap

Default foreground color
Default foreground color
NULL

Widget Attributes A-15

Table A-12:

(continued)

Attribute Name

Data Type

Default

DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNstyle

Opaque *
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char
unsigned char

DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth

DwtCallbackPtr
XtTranslations
Dimension

DwtNmarginHeight

Dimension

DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNgrabKeySyms

Boolean
Boolean
unsigned char
KeySym

DwtNgrabMergeTranslations

XtTranslations

NULL
The default XUI Toolkit font
NULL
DwtDirectionRightDown
DwtFontUnits
For DwtDialogBoxCreate,
the default is DwtWorkarea.
For
DwtDialogBoxPopupCreat
the default is DwtModeless.
NULL
NULL
For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreat
the default is 3 pixels.
For DwtDialogBoxCreate,
the default is One pixel.
For
DwtDialogBoxPopupCreat
the default is 3 pixels.
False
True
DwtResizeGrowOnly
The default array contains the 1
key symbol.
The default syntax is:
"-Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSNEXTO
Shift<KeyPress>Oxff09:
DWTDIMOVEFOCUSPREVO

Table A-13: Widget-Specific Attributes for the Pop-Up Dialog
Box Widget
Attribute Name

Data Type

Default

DwtNtitle

DwtCompString

When DwtNstyle is
DwtModal, the default is NULL

A-16 Widget Attributes

Table A-13:

(continued)

Attribute Name

Data Type

Default
When DwtNstyle is
DwtModeless, the default is the
widget name

DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

DwtCallbackPtr
DwtCallbackPtr
Boolean

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton
DwtNautoUnrealize

Boolean
Widget
Widget
Boolean

NULL
NULL
True for modal dialog box
False for modeless dialog box
True (that is, no window
manager resize button)
True

NULL
NULL
False

A.7 File Selection Widget
Table A-14: Attributes Inherited by the File Selection Widget
Attribute Name

Data Type

Default

DwtNx
DwtNy
DwtNwidth

Position
Position
Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap

Dimension
Pixel
Pixmap
Pixel
Pixmap

Centered in the parent window
Centered in the parent window
The width of the list box, plus the
width of the push buttons, plus
three times
DwtNmarginWidth. The list
box will grow to accommodate
items wider than the title.
The height of the list box, plus
the height of the text edit field,
plus the height of the label, plus
three times
DwtNmarginHeight.
One pixel
Default foreground color

Core Attributes

NULL
Default background color

NULL

Widget Attributes A-17

Table A-14:

(continued)

Attribute Name

Data Type

Default

DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive aI
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char
unsigned char
DwtCallbackPtr
XtTranslations
Dimension
Dimension
Boolean
Boolean
unsigned char
Boolean

DwtNtitle
DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

DwtCompString
DwtCallbackptr
DwtCallbackptr
Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
Widget
Widget

A-18 Widget Attributes

Table A-14:

(continued)

Attribute Name

Data Type

Default

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackptr
DwtCallbackPtr
DwtCallbackPtr
int
DwtCompString *
int
Boolean
DwtCompString

"Items"

Selection Attributes
DwtNlabel
DwtNvalue
DwtNokLabel
DwtNcancelLabel
DwtNactivateCallback
DwtNcancelCallback
DwtNnoMatchCallback
DwtNvisibleItemsCount
DwtNitems
DwtNitemsCount
DwtNmustMatch
DwtNselectionLabel

"Ok"
"Cancel"

NULL
NULL
NULL
8

NULL
Zero
False
"Files in"

Table A-15: Widget-Specific Attributes for the File Selection
Widget
Attribute Name

Data Type

Default

DwtNfilterLabel
DwtNapplyLabel
DwtNdirMask
DwtNdirSpec
DwtNfileSearchProc

DwtCompString
DwtCompString
iJWtCompString
DwtCompString
VoidProc

"File filter"
"Filter"

"* *"
FileSelectionSearch

CULTRIX default directory file
DwtNlistUpdated
DwtNfileToExternProc
DwtNfileToInternProc
DwtNmaskToExternProc
DwtNmaskToInternProc

Boolean
VoidProc
VoidProc
VoidProc
VoidProc

search function)
False

NULL
NULL
NULL
NULL

Widget Attributes A-19

A.a Help Widget
Table A-16: Attributes Inherited by the Help Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNhe:i..ght

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Cannot be set by the caller. The
help menu widget calculates the
width, based on the size of the
text window (DwtNcols and
DwtNrows).
Cannot be set by the caller. The
help menu widget calculates the
height, based on the size of the
text window (DwtNcols and
DwtNrows).
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Attribute Name
Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensit~ve and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData

A-20 Widget Attributes

Pixel
Pixel
Pixmap
Opaque *

Default foreground color
Default foreground color

NULL
NULL

Table A-16:

(continued)

Attribute Name

Data Type

Default

DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

unsigned char
DwtFontList
DwtCallbackPtr

DwtDirectionRightDown
The default XUI Toolkit font
NULL

Table A-17: Widget-Specific Attributes for the Help Widget
Attribute Name

Data Type

Default

DwtNaboutLabel
DwtNaddtopicLabel
DwtNapplicationName
DwtNbadframeMessage
DwtNbadlibMessage
DwtNcacheHelpLibrary
DwtNcloseLabel
DwtNcols

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
Boolean
DwtCompString
int

DwtCompString
Boolean
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtFontList

DwtNhelpLabel

DwtCompString

"About"
" Additional topics"
NULL
"Couldn't find frame !CS"
"Couldn't open library !CS"
False
"Exit"
Language-dependent. The
American English default is 55.
"Copy"
True
"Dismiss"
"Edit"
"Error opening file !CS"
"Exit"
"File"
NULL
"Glossary"
NULL
"Go Back"
"Go Back"
"Go To Overview"
"Go To"
"Go To Topic"
"Acknowledge"
Language-dependent. The
American English default is "*-TERMINAL-MEDIUM-RNARROW--*-140*-*-C-*-IS08859-1"
"Using Help"

Widget Attributes A-21

Table A-17:

(continued)

Attribute Name

Data Type

Default

DwtNhelphelpLabel
DwtNhelpOnHelpTitle
DwtNhelpontitleLabel
DwtNhelptitleLabel
DwtNhistoryLabel
DwtNhistoryboxLabel
DwtNkeywordLabel
DwtNkeywordsLabel
DwtNlibrarySpec
DwtNlibraryType
DwtNnokeywordMessage
DwtNnotitleMessage
DwtNnulllibMessage
DwtNmapCallback
DwtNoverviewTopic
DwtNrows

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
int
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCompString
int

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackPtr
DwtCompString
DwtCompString
DwtCompString
DwtCompString

"Overview"
"Using Help"
"Help on"
"Help"
"History... "
"Search Topic History"
"Keyword... "
"Keyword"
NULL
DwtTextLibrary
"Couldn't find keyword !CS"
"No title to match string !CS"
"No library specified\n"
NULL
NULL
Language-dependent. The
American English default is 20.
"Save As ... "
"Apply"
"Search Topic Keywords"
"Search"
"Search Topic Titles"
"Select All"
"Title... "
"Title"
"Topic Titles "
NULL
"View"
"Visit Glossary"
"Visit"
"Visit Topic"

A-22 Widget Attributes

A.9 Label Widget
Table A-18: Attributes Inherited by the Label Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
The width of the label or pixmap,
plus two times
DwtNmarginWidth
The height of the label or pixmap,
plus two times
DwtNmarginHeight
zero pixels
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackptr

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDown
The default XVI Toolkit font

NULL

Widget Attributes A-23

Table A-19: Widget-Specific Attributes for the Label Widget
Attribute Name

Data Type

Default

DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap
Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter
NULL
Zero
Zero
Zero
Zero
True, if the widget is created
with a width and height of zero
False, if the widget is created
with a non-zero width and height

A.10 Label Gadget
Table A-20: Attributes Inherited by the Label Gadget
Attribute Name

Data Type

Default

Rectangle Attributes
DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

A-24 Widget Attributes

Table A-20:

(continued)

Table A-21: Widget-Specific Attributes for the the Label Gadget

A.11

Attribute Name

Data Type

Default

DwtNlabel
DwtNalignment
DwtNdirectionRToL
DwtNhelpCallback

DwtCompString
unsigned char
Boolean
DwtCallbackPtr

Widget name
DwtAlignmentCenter
False

NULL

List Box Widget
Table A-22: Attributes Inherited by the List Box Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
Set as large as necessary to hold
the longest item without
exceeding the size of its parent
Set as large as necessary to hold
the number of items specified by
DwtNvisibleltemsCount,
without exceeding the size of the
parent widget
One pixel
Default foreground color

DwtNaccelerators

XtTranslations

Attribute Name

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL

Widget Attributes A-25

Table A-22:

(continued)

Attribute Name

Data Type

Default

DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsign~d char
NOT SUPPORTED
NOT SUPPORTED

Default foreground color
Default foreground color

Widget
Widget
Widget
Boolean
Boolean

NULL
NULL
NULL

NULL
NULL
DwtDirectionRightDov

Scroll Window Attributes
DwtNhorizontalScrollBar
DwtNverticalScrollBar
DwtNworkWindow
DwtNshownValueAutomaticHoriz
DwtNshownValueAutomaticVert

True
False

Table A-23: Widget-Specific Attributes for the List Box Widget
Attribute Name

Data Type

DwtNmarginWidth
DwtNmarginHeight
DwtNspacing
DwtNitems
DwtNitemsCount
DwtNselectedltems
DwtNselectedltemsCount
DwtNvisibleltemsCount

Dimension
Dimension
Dimension
DwtCompString *
int
DwtCompString *
int
int

A-26 Widget Attributes

Default
10 pixels

4 pixels
1 pixel

NULL
Zero

NULL
Zero
As many items as can fit in the
core attribute DwtNheight.
The minimum is 1.

Table A-23:

{continued}

Attribute Name

Data Type

Default

DwtNsingleSelection
DwtNresize
DwtNhorizontal
DwtNsingleCallback
DwtNsingleConfirmCallback
DwtNextendCallback
DwtNextendConfirmCallback

Boolean
Boolean
Boolean
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr

True
True
False
NULL
NULL
NULL
NULL

A.12 Main Window Widget
Table A-24: Attributes Inherited by the Main Window Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Detennined by the geometry
manager
Detennined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Core Attributes

Widget Attributes A-27

Table A-24:

(continued)

Attribute Name

Data Type

Default

Pixel
NOT SUPPORTED
NOT SUPPORTED
Opaque *
unsigned char
NOT SUPPORTED
DwtCallbackptr

Default foreground color

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

NULL
DwtDirectionRightDown

NULL

Table A-25: Widget-Specific Attributes for the Main Window
Widget
Attribute Name

Data Type

Default

DwtNcommandWindow
DwtNworkWindow
DwtNmenuBar
DwtNhorizontalScrollBar
DwtNverticalScrollBar
DwtNacceptFocus
DwtNfocusCallback

Widget
Widget
Widget
Widget
Widget
Boolean
DwtCallbackPtr

NULL
NULL
NULL
NULL
NULL
False

NULL

A.13 Menu Bar Widget
Table A-26: Attributes Inherited by the Menu Bar Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

Detennined by the geometry
manager
Detennined by the geometry
manager
16 pixels

Core Attributes

A-28 Widget Attributes

Table A-26:

(continued)

Attribute Name

Data Type

Default

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Number of lines needed to display
all entries
One pixel
Default foreground color

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

NULL
Default background color

NULL
Default color map
True
Note that setting the sensitivity of
the menu bar causes all widgets
contained in that menu bar to be
set to the same sensitivity as the
menu bar.
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

NULL

Dimension
Dimension
Dimension
unsigned char
Boolean
short

One pixel
Zero pixels
Three pixels
DwtOrientationVertical
True
Zero pixels

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDown
Used only by gadget children

Menu Attributes
DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder

Widget Attributes A-29

Table A-26:

(continued)

Attribute Name

Data Type

Default

DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

Boolean
unsigned char
unsigned char

True
DwtAlignmentBeginning
DwtMenuPackingTight(fur
all menu types except for radio
boxes)
DwtMenuPackingColumn~or

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

Widget
DwtCallbackPtr
Widget
Boolean
Boolean

radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)

NULL
Radio boxes, however, default to
the togglebuttonwidgetc1ass.
Zero

NULL
NULL
True
True

A.14 Menu, Pull-Down Menu, and Pop-Up Menu Widgets
TableA-27: Attributes Inherited by the Menu Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

Determined by the geometry
manager
Determined by the geometry
manager
If menu orientation is
DwtOrientationVertical,
default is the maximum entry
DwtNwidth or 16 pixels.

Core Attributes

A-30 Widget Attributes

Table A-27:

(continued)

Attribute Name

Data Type

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Default
If menu orientation is
DwtOrientationHorizontal,
default is the sum of
DwtNwidth and
DwtNspacing or 16 pixels.
If menu orientation is
DwtOrientationVertical,
default is the sum of
DwtNheight and
DwtNspacing or 16 pixels.
If menu orientation is
DwtOrientationHorizontal,
default is the maximum entry
DwtNheight or 16 pixels.
One pixel
Default foreground color

NULL
Default background color

NULL
Default color map
True
Setting the sensitivity of the menu
causes all widgets contained in
that menu to be set to the same
sensitivity.
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDown
The default XVI Toolkit font

NULL
Widget Attributes A-31

Table A-28: Attributes Inherited by the Pull-Down Menu and
Pop-Up Menu Widgets
Data Type

Default

DwtNx

Position

DwtNy

position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

For DwtMenuPopupCreate,
determined by the geometry
manager
For
DwtMenuPulldownCreate,
this attribute is not supported
For DwtMenuPopupCreate,
determined by the geometry
manager
For
DwtMenuPulldownCreate,
this attribute is not supported
Set as large as necessary to hold
all child widgets
Set as large as necessary to hold
all child widgets
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Attribute Name
Core Attributes

A-32 Widget Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Table A-28:

(continued)

Attribute Name

Data Type

Default

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color

Common Attributes

DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font

NULL

Menu Attributes

DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char
unsigned char

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

Widget
DwtCallbackPtr
Widget
Boolean
Boolean

Zero pixels
3 pixels
Three pixels
DwtOrientationVertical
True
Zero pixels
True
DwtAlignmentBeginning
DwtMenuPackingTight(fur
all menu types except for radio
boxes)
DwtMenuPackingColumn(fur
radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)

NULL
Radio boxes, however, default to
the togglebuttonwidgetc1ass.
Zero

NULL
NULL
True
True

Widget Attributes A-33

Table A-29: Widget-Specific Attributes for the Pull-Down Menu
and Pop-Up Menu Widgets
Attribute Name

Data Type

Default

DwtNmapCallback
DwtNunmapCallback

DwtCallbackptr
DwtCallbackPtr

NULL
NULL

Table A-30: Widget-Specific Attributes for the Menu Widget
Attribute Name

Data Type

Default

DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char
unsigned char

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

Widget
DwtCallbackptr
Widget
Boolean
Boolean

Zero pixels
3 pixels
Three pixels
DwtOrientationVertical
True
Zero pixels
True
DwtAlignmentBeginning
DwtMenuPackingTight(for
all menu types except for radio
boxes)
DwtMenuPackingColumn(fur
radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)
NULL
Radio boxes, however, default to
the togglebuttonwidgetclass.
Zero
NULL
NULL
True
True

A-34 Widget Attributes

A.15 Message Box Widget
Table A-31: Attributes Inherited by the Message Box Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Dialog Pop-Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNtitle
DwtNstyle

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char

Default foreground color
Default foreground color

NULL
NULL
The default XUI Toolkit font

NULL

Widget name
DwtModal

Widget Attributes A-35

Table A-31:

(continued)

Attribute Name

Data Type

Default

DwtNmapCallback
DwtNunmapCallback
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNtakeFocus

DwtCallbackPtr
DwtCallbackptr
DwtCallbackPtr
NOT SUPPORTED
Dimension
Dimension
Boolean
NOT SUPPORTED
unsigned char
Boolean

NULL
NULL
NULL

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
NOT SUPPORTED
NOT SUPPORTED

12 pixels
10 pixels
False
DwtResizeShrinkWrap
True for modal dialog box
Fa 1 s e for modeless dialog box
True (that is, no window
manager resize button)
True

Table A-32: Widget-Specific Attributes for the Message Box
Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNokLabel
DwtNyesCallback
DwtNsecondLabel
DwtNlabelAlignment
DwtNsecondLabelAlignment
DwtNiconPixmap

DwtCompString
DwtCompString
DwtCallbackptr
DwtCompString
unsigned char
unsigned char
Pixmap

Widget name
"Acknowledged"

A-36 Widget Attributes

NULL
NULL
DwtAlignmentCenter
DwtAlignmentBeginning
The default is the standard icon
provided for each message-class
widget as follows: (1) the default
caution box icon is an
exclamation point; (2) the default
message box icon is an asterisk;
(3) the default work box icon is
the wait cursor (watch). See the
XUI Style Guide for illustrations
of the icons for each message
class widget.

A.16 Option Menu Widget
Table A-33: Attributes Inherited by the Option Menu Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

Determined by the geometry
manager
Determined by the geometry
manager
Set as large as necessary to hold
all child widgets
Set as large as necessary to hold
all child widgets
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Core Attributes

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList

DwtNhelpCallback

DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
Used only by gadget children
NULL

Widget Attributes A-37

Table A-33:

(continued)
Data Type

Default

DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char
unsigned char

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

Widget
DwtCallbackPtr
Widget
Boolean
Boolean

Attribute Name
Menu Attributes

Table A-34: Widget-Specific Attributes for the Option Menu
Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNsubMenuld

DwtCompString
Widget

Widget name
Zero

A-38 Widget Attributes

A.17 Pull-Down Menu Entry Widget
Table A-35: Attributes Inherited by the Pull Down Menu Entry
Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
The DwtNlabel width, plus the
DwtNhotSpotP ixmap width or
the DwtNpixmap width, plus
DwtNmarginWidth times two
The DwtNlabel or
DwtNpixmap height, plus
DwtNmarginHeight times two
zero pixels
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char

Default foreground color
Default foreground color

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL

NULL
NULL
DwtDirectionRightDown

Widget Attributes A-39

Table A-35:

(continued)

Attribute Name

Data Type

Default

DwtNfont
DwtNhelpCallback

DwtFontList
DwtCallbackPtr

The default XUI Toolkit font
NULL

DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

Label Attributes

Table A-36: Widget-Specific Attributes for the Pull Down Menu
Entry Widget
Attribute Name

Data Type

Default

DwtNsubMenuld
DwtNactivateCallback
DwtNpullingCallback
DwtNhotSpotPixmap

Widget
DwtCallbackptr
DwtCallbackPtr
Pixmap

NULL
NULL
NULL
NULL

A-40 Widget Attributes

A.18 Pull-Down Menu Entry Gadget
Table A-37: Attributes Inherited by the Pull-Down Menu Entry
Gadget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

Rectangle Attributes

Label Gadget Attributes
DwtNlabel
DwtNalignment
DwtNdirectionRToL
DwtNhelpCallback

DwtCompString
unsigned char
Boolean
DwtCallbackPtr

Widget name
DwtAlignmentCenter
False

NULL

Table A-3S: Widget-Specific Attributes for the the Pull-Down
Menu Entry Gadget
Attribute Name

Data Type

Default

DwtNsubMenuld
DwtNactivateCallback
DwtNpullingCallback

Widget
DwtCallbackPtr
DwtCallbackptr

NULL
NULL
NULL

Widget Attributes A-41

A.19 Push Button Widget
Table A-39: Attributes Inherited by the Push Button Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Detennined by the geometry
manager
Detennined by the geometry
manager
The width of the label or pixmap
plus DwtNmarginWidth times
two
The height of the label or pixmap
plus DwtNmarginHeight
times two
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font
NULL

Core Attributes

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

A-42 Widget Attributes

Table A-39:

(continued)

Attribute Name

Data Type

Default

DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap
Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter

Label Attributes

NULL
Zero
Zero
Zero
Zero
True, if the widget is created
with a width and height of zero
F a Is e, if the widget is created
with a non-zero width and height

Table A-40: Widget-Specific Attributes for the Push Button
Widget
Attribute Name

Data Type

Default

DwtNbordHighlight
DwtNfillHighlight
DwtNshadow
DwtNactivateCallback
DwtNarmCallback
DwtNdisarmCallback
DwtNacceleratorText
DwtNbuttonAccelerator
DwtNinsensitivePixmap

Boolean
Boolean
Boolean
DwtCallbackptr
DwtCallbackPtr
DwtCallbackPtr
DwtCompString
char *
Pixmap

False
False
True

NULL
NULL
NULL
NULL
NULL
NULL

Widget Attributes A-43

A.20 Push Button Gadget
Table A-41: Attributes Inherited by the Push Button Gadget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
The width of the label plus
margins
The height of the label plus
margins
1 pixel
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

Rectangle Attributes

Table A-42: Widget-Specific Attributes for the the Push Button
Gadget
Attribute Name

Data Type

Default

DwtNlabel
DwtNactivateCallback
DwtNacceleratorText
DwtNbuttonAccelerator

DwtCompString
DwtCallbackptr
DwtCompString
char *

NULL
NULL
NULL
NULL

A-44 Widget Attributes

A.21

Radio Box Widget
Table A-43: Attributes Inherited by the Radio Box Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Determined by the geometry
manager
Determined by the geometry
manager
Set as large as necessary to hold
all child widgets
Set as large as necessary to hold
all child widgets
One pixel
Default foreground color
NULL
Default background color
NULL
Default color map
True
Setting the sensitivity of the radio
box causes all widgets contained
in that radio box to be set to the
same sensitivity.
The bitwise AND of the parent
widget'S DwtNsensi ti ve and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Pixel
Pixel
Pixmap
Opaque *
unsigned char

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown

Core Attributes

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL

Widget Attributes A-45

Table A-43:

(continued)

Attribute Name

Data Type

Default

DwtNfont
DwtNhelpCallback

DwtFontList
DwtCallbackPtr

The default XVI Toolkit font

Dimension
Dimension
Dimension
unsigned char
Boolean
short
Boolean
unsigned char
unsigned char

Zero pixels
3 pixels
Three pixels
DwtOrientationVertical
True
Zero pixels
True
DwtAlignmentBeginning

NULL

Menu Attributes
DwtNspacing
DwtNmarginHeight
DwtNmarginWidth
DwtNorientation
DwtNadjustMargin
DwtNentryBorder
DwtNmenuAlignment
DwtNentryAlignment
DwtNmenuPacking

DwtMenuPackingTight~or

all menu types except for radio
boxes)
DwtMenuPackingColumn~or

DwtNmenuNumColumns
DwtNmenuRadio

short
Boolean

DwtNradioAlwaysOne
DwtNmenuIsHomogeneous

Boolean
Boolean

DwtNmenuEntryClass

WidgetClass

DwtNmenuHistory
DwtNentryCallback
DwtNmenuHelpWidget
DwtNchangeVisAtts
DwtNmenuExtendLastRow

A.22 Scale Widget

A-46 Widget Attributes

Widget
DwtCallbackPtr
Widget
Boolean
Boolean

radio boxes)
One row or column
False
True (for radio boxes)
True
False
True (for radio boxes)

NULL
Radio boxes, however, default to
the togglebuttonwidgetclass.
Zero

NULL
NULL
True
True

Table A-44: Attributes Inherited by the Scale Widget
Data Type

Default

DwtNx

Position

DwtNy

position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Attribute Name
Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensi ti ve and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font

NULL

Widget Attributes A-47

Table A-45: Widget-Specific Attributes for the Scale Widget
Attribute Name

Data Type

Default

DwtNvalue
DwtNtitle
DwtNorientation
DwtNscaleWidth
DwtNscaleHeight
DwtNminValue
DwtNmaxValue
DwtNdecimalPoints
DwtNshowValue
DwtNdragCallback
DwtNvalueChangedCallback

int
DwtCompString
unsigned char
Dimension
Dimension
int
int
short
Boolean
DwtCallbackPtr
DwtCallbackptr

zero
Scale name
DwtOrientationHorizontal
100 pixels
20 pixels
Zero
100
Zero
True

NULL
NULL

A.23 Scroll Bar Widget
Table A-46: Attributes Inherited by the Scroll Bar Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Core Attributes

A-48 Widget Attributes

NULL
Default background color

NULL
Default color map
True

Table A-46:

(continued)

Attribute Name

Data Type

Default

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window
NULL
True
The parent screen
NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
DwtCallbackPtr

Default foreground color
Default foreground color
NULL
NULL
DwtDirectionRightDown
NULL

Table A-47: Widget-Specific Attributes for the Scroll Bar Widget
Attribute Name

Data Type

Default

DwtNvalue
DwtNminValue
DwtNmaxValue
DwtNorientation
DwtNtranslationsl
DwtNtranslations2
DwtNshown
DwtNinc
DwtNpagelnc
DwtNvalueChangedCallback
DwtNunitlncCallback
DwtNunitDecCallback
DwtNpagelncCallback
DwtNpageDecCallback

int
int
int
unsigned char
XtTranslations
XtTranslations
int
int
int
DwtCallbackPtr
;])wtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackptr

Zero
Zero
100
DwtOrientationVertical
NULL
NULL
10 units
10 units
10 units
NULL
NULL
NULL
NULL
NULL

Widget Attributes A-49

Table A-47:

(continued)

Attribute Name

Data Type

Default

DwtNtoTopCallback
DwtNtoBottomCallback
DwtNdragCallback
DwtNshowArrows

DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
Boolean

NULL
NULL
NULL
True

A.24 Scroll Window Widget
Table A-48: Attributes Inherited by the Scroll Window Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean

Determined by the geometry
manager
Determined by the geometry
manager
Widget-specific
Widget-specific
One pixel
Default foreground color

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged

XtTranslations
int
XtTranslations
Boolean

Attribute Name
Core Attributes

A-50 Widget Attributes

NULL
Default background color

NULL
Default color map
True
Setting the sensitivity of the scroll
window causes all widgets
contained in that window to be
set to the same sensitivity as the
scroll window.
The bitwise AND of the parent
widget'S DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True

Table A-48:

(continued)

Attribute Name

Data Type

Default

DwtNscreen
DwtNdestroyCallback

Screen *
DwtCallbackPtr

The parent screen

Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
NOT SUPPORTED

Default foreground color
Default foreground color

NULL

Common Attributes
DwtNf ore.ground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

NULL
NULL
DwtDirectionRightDown

Table A-49: Widget-Specific Attributes for the Scroll Window
Widget
Attribute Name

Data Type

Default

DwtNhorizontalScrollBar
DwtNverticalScrollBar
DwtNworkWindow
DwtNshownValueAutomaticHoriz
DwtNshownValueAutomaticVert

Widget
Widget
Widget
Boolean
Boolean

NULL
NULL
NULL
True
True

A.25 Selection Widget
Table A-50: Attributes Inherited by the Selection Widget
Attribute Name

Data Type

Default

Position
Position

Centered in the parent window
Centered in the parent window

Core Attributes
DwtNx
DwtNy

Widget Attributes A-51

Table A-50:

(continued)

Attribute Name

Data Type

Default

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestor8ensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

The width of the list box, plus thl
width of the push buttons, plus
three times
DwtNmarginWidth. The list
box will grow to accommodate
items wider than the title.
The height of the list box, plus
the height of the text edit field,
plus the height of the label, plus
three times
DwtNmarginHeight.
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget'S DwtNsensitive ane
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

A-52 Widget Attributes

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
unsigned char
unsigned char
unsigned char
DwtCallbackptr
XtTranslations
Dimension

Default foreground color
Default foreground color

NULL
NULL
The default XUI Toolkit font

NULL
DwtDirectionRightDown
DwtFontUnits
DwtModal

NULL
NULL
5 pixels

Table A-50:

(continued)

Attribute Name

Data Type

Default

DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNnoResize

Dimension
Boolean
Boolean
unsigned char
Boolean

DwtNtitle
DwtNmapCallback
DwtNunmapCallback
DwtNtakeFocus

DwtCompString
DwtCallbackptr
DwtCallbackptr
Boolean

5 pixels
False
True
DwtResizeGrowOnly
True (that is, no window
manager resize button)
"Open"

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
Widget
Widget

NULL
NULL
True for modal dialog box
F a I s e for modeless dialog box
True

NULL
NULL

Table A-51: Widget-Specific Attributes for the Selection Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNvalue
DwtNokLabel
DwtNcancelLabel
DwtNactivateCallback
DwtNcancelCallback
DwtNnoMatchCallback
DwtNvisibleltemsCount
DwtNitems
DwtNitemsCount
DwtNmustMatch
DwtNselectionLabel

DwtCompString
DwtCompString
DwtCompString
DwtCompString
DwtCallbackptr
DwtCallbackPtr
DwtCallbackptr
int
DwtCompString *
int
Boolean
DwtCompString

"Items"
"Ok"
"Cancel"

NULL
NULL
NULL
8

NULL
Zero
False
"Selection"

Widget Attributes A-53

A.26 Separator Widget
Table A-52: Attributes Inherited by the Separator Widget
Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
int
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
3 pixels
3 pixels
zero
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
NOT SUPPORTED
Boolean
Screen *
DwtCallbackPtr

Attribute Name
Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Label Attributes

A-54 Widget Attributes

Pixel
Pixel
Pixmap
Opaque *
unsigned char
NOT SUPPORTED
NOT SUPPORTED

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDown

Table A-52:

(continued)

Attribute Name

Data Type

Default

DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

Table A-53: Widget-Specific Attributes for the Separator Widget
Attribute Name

Data Type

Default

DwtNorientation

unsigned char

DwtOrientationHorizontal

A.27 Separator Gadget
Table A-54: Attributes Inherited by the Separator Gadget
Attribute Name

Data Type

Default

Rectangle Attributes
DwtNx

position

DwtNy

Position

DwtNwidth
DwtNheight

Dimension
Dimension

Determined by the geometry
manager
Determined by the geometry
manager
3 pixels
3 pixels

Widget Attributes A-55

Table A-54:

(continued)

Attribute Name

Data Type

Default

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

zero
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

Table A-55: Widget-Specific Attributes for the the Separator
Gadget
Attribute Name

Data Type

Default

DwtNorientation

unsigned char

DwtOrientationHorizontal

A.28 Simple Text Widget
Table A-56: Attributes Inherited by the Simple Text Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNbo:r:der
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap

Dimension
Pixel
Pixmap
Pixel
Pixmap

Detennined by the geometry
manager
Detennined by the geometry
manager
Set as large as necessary to
display the DwtNrows with the
specified DwtNmarginWidth
As large as necessary to display
the DwtNcols with the
specified DwtNmarginHeight
One pixel
Default foreground color

Core Attributes

A-56 Widget Attributes

NULL
Default background color
NULL

Table A-56:

(continued)

Attribute Name

Data Type

Default

DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Colormap
Boolean
Boolean

Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackptr

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Table A-57: Widget-Specific Attributes for the Simple Text
Widget
Attribute Name

Data Type

Default

Dimension
Dimension
Dimension
Dimension
DwtTextPosition
Boolean
Boolean
Boolean
Boolean
char *
Boolean
int
DwtCallbackPtr
DwtCallbackptr
DwtCallbackPtr
DwtCallbackPtr
Boolean
Boolean
int
Pixel

2 pixels
Two pixels
20 characters
1 character
Zero
False
False
True
True
True
2**31-1

NULL
NULL
NULL
NULL
True
True
Zero
The current server's default
foreground

Widget Attributes A-57

Table A-57:

(continued)

Attribute Name

Data Type

Default

DwtNfont
DwtNblinkRate
DwtNscrollLeftSide
DwtNhalfBorder
DwtNpendingDelete
DwtNuserData

DwtFontList
int
Boolean
Boolean
Boolean
Opaque *

The current server font list.
500 milliseconds
False
True
True

NULL

A.29 Toggle Button Widget
Table A-58: Attributes Inherited by the Toggle Button Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations

XtTranslations
int
XtTranslations

Core Attributes

A-58 Widget Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL

Table A-58:

(continued)

Attribute Name

Data Type

Default

DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

Boolean
Screen *
DwtCallbackPtr

True
The parent screen

Pixel
Pixel
Pixmap
Opaque *
unsigned char
DwtFontList
DwtCallbackPtr

Default foreground color
Default foreground color

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

NULL
NULL
DwtDirectionRightDown
The default XUI Toolkit font

NULL

Label Attributes
DwtNlabelType
DwtNlabel
DwtNmarginWidth

unsigned char
DwtCompString
Dimension

DwtNmarginHeight

Dimension

DwtNalignment
DwtNpixmap
DwtNmarginLeft
DwtNmarginRight
DwtNmarginTop
DwtNmarginBottom
DwtNconformToText

unsigned char
Pixmap
Dimension
Dimension
Dimension
Dimension
Boolean

DwtCString
Widget name
Two pixels for text
Zero pixels for pixmap
Two pixels for text
Zero pixels for pixmap
DwtAlignmentCenter

NULL
Zero
Zero
Zero
Zero
True, if the widget is created
with a width and height of zero
False, if the widget is created
with a non-zero width and height

Widget Attributes A-59

Table A-59: Widget-Specific Attributes for the Toggle Button
Widget
Attribute Name

Data Type

Default

DwtNshape
DwtNvisibleWhenOff
DwtNspacing
DwtNpixmapOn
DwtNpixma.pOff
DwtNvalue
DwtNarmCallback
DwtNdisarmCallback
DwtNvalueChangedCallback
DwtNindicator

unsigned char
Boolean
short
Pixmap
Pixmap
Boolean
DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
Boolean

DwtRectangular
True
4 pixels

DwtNacceleratorText
DwtNbuttonAccelerator
DwtNinsensitivePixmapOn
DwtNinsensitivePixmapOff

DwtCompString
char *
Pixmap
Pixmap

NULL
NULL
NULL
NULL

NULL
NULL
False

NULL
NULL
NULL
True when the label is
DwtCString
False Wilen the label is
DwtPixmap

A.30 Toggle Button Gadget
Table A-60: Attributes Inherited by the Toggle Button Gadget
Attribute Name

Data Type

Default

Rectangle Attributes
DwtNx

Position

DwtNy

Position

DwtNwidth

Dimension

DwtNheight

Dimension

DwtNborderWidth
DwtNsensitive
DwtNancestorSensitive

Dimension
Boolean
Boolean

A-60 Widget Attributes

Table A-60:

(continued)

Attribute Name

Data Type

Default

DwtCompString
unsigned char
Boolean
DwtCallbackPtr

Widget name
DwtAlignmentCenter '
False

Label Attributes
DwtNlabel
DwtNalignment
DwtNdirectionRToL
DwtNhelpCallback

NULL

Table A-61: Widget-Specific Attributes for the the Toggle Button
Gadget

A.31

Attribute Name

Data Type

Default

DwtNshape
DwtNvalue
DwtNvisibleWhenOff
DwtNvalueChangedCallback
DwtNbuttonAccelerator
DwtNacceleratorText

unsigned char
Boolean
Boolean
DwtCallbackptr
char *
DwtCompString

DwtRectangular
False
True
NULL
NULL
NULL

Window Widget
Table A-62: Attributes Inherited by the Window Widget
Attribute Name

Data Type

Default

DwtNx

Position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap

Dimension
Dimension
Dimension
Pixel
Pixmap

Detennined by the geometry
manager
Detennined by the geometry
manager
Widget-specific
Widget-specific
One pixel
Default foreground color

Core Attributes

NULL

Widget Attributes A-61

Table A-62:

(continued)

Attribute Name

Data Type

Default

DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive

Pixel
Pixmap
Colormap
Boolean

Default background color

DwtNancestorSensitive

Boolean

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

NULL
Default color map
True
Setting the sensitivity of the
window causes all widgets
contained in that window to be
set to the same sensitivity as the
window.
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes

NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Common Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNdirectionRToL
DwtNfont
DwtNhelpCallback

Pixel
Pixel
Pixmap
Opaque *
unsigned char

Default foreground color
Default foreground color

NULL
NULL
DwtDirectionRightDown

NOT SUPPORTED
NOT SUPPORTED

Table A-S3: Widget-Specific Attributes for the Window Widget
Attribute Name

Data Type

Default

DwtNexposeCallback

DwtCallbackPtr

NULL

A-62 Widget Attributes

A.32 Work-in-Progress Box Widget
Table A-64: Attributes Inherited by the Work-in-Progress Box
Widget
Attribute Name

Data Type

Default

DwtNx

position

DwtNy

Position

DwtNwidth
DwtNheight
DwtNborderWidth
DwtNborder
DwtNborderPixmap
DwtNbackground
DwtNbackgroundPixmap
DwtNcolormap
DwtNsensitive
DwtNancestorSensitive

Dimension
Dimension
Dimension
Pixel
Pixmap
Pixel
Pixmap
Colormap
Boolean
Boolean

Detennined by the geometry
manager
Detennined by the geometry
manager
5 pixels
5 pixels
One pixel
Default foreground color

DwtNaccelerators
DwtNdepth
DwtNtranslations
DwtNmappedWhenManaged
DwtNscreen
DwtNdestroyCallback

XtTranslations
int
XtTranslations
Boolean
Screen *
DwtCallbackPtr

Core Attributes

NULL
Default background color

NULL
Default color map
True
The bitwise AND of the parent
widget's DwtNsensitive and
DwtNancestorSensitive
attributes
NULL
Depth of the parent window

NULL
True
The parent screen

NULL

Dialog Pop-Up Attributes
DwtNforeground
DwtNhighlight
DwtNhighlightPixmap
DwtNuserData
DwtNfont
DwtNhelpCallback
DwtNdirectionRToL
DwtNunits
DwtNtitle
DwtNstyle

Pixel
Pixel
Pixmap
Opaque *
DwtFontList
DwtCallbackPtr
NOT SUPPORTED
NOT SUPPORTED
DwtCompString
unsigned char

Default foreground color
Default foreground color

NULL
NULL
The default XUI Toolkit font

NULL

Widget name
DwtModal

Widget Attributes A-63

Table A-64:

(continued)

Attribute Name

Data Type

Default

DwtNmapCallback
DwtNunmapCallback
DwtNfocusCallback
DwtNtextMergeTranslations
DwtNmarginWidth
DwtNmarginHeight
DwtNdefaultPosition
DwtNchildOverlap
DwtNresize
DwtNtakeFocus

DwtCallbackPtr
DwtCallbackPtr
DwtCallbackPtr
NOT SUPPORTED
Dimension
Dimension
Boolean
NOT SUPPORTED
unsigned char
Boolean

NULL
NULL
NULL

DwtNnoResize

Boolean

DwtNautoUnmanage
DwtNdefaultButton
DwtNcancelButton

Boolean
NOT SUPPORTED
NOT SUPPORTED

12 pixels

10 pixels
False
DwtResizeShrinkWrap
True for modal dialog box
False for modeless dialog box
True (that is, no window
manager resize button)
True

Table A-65: Widget-Specific Attributes for the Work-in-Progress
Box Widget
Attribute Name

Data Type

Default

DwtNlabel
DwtNcancelLabel
DwtNcancelCallback

DwtCompString
DwtCompString
DwtCallbackptr

Widget name
"Cancel"

A-64 Widget Attributes

NULL

Index

common attributes (cont.)

callback
definition, 8-6, 8-8

DwtMainWindowCreate, 2-6, A-28
DwtMenuBarCreate, 2-11, A-29
DwtMenuCreate, 4-8, 4-9, A-31, A-33

callback structure, 1-10t
ClipboardBadFormat, 8-26

DwtMenuPopupCreate, 4-8, 4-9, A-31,

ClipboardFaiJ, 8-26

A-33
DwtMenuPulldownCreate, 4-8, 4-9, A-31 ,

ClipboardLocked, 8-6, 8-8, 8-9, 8-11, 8-11,
8-13,8-14,8-15,8-17,8-18,8-19,
8-21,8-22,8-23,8-25,8-25,8-26
ClipboardNoData, 8-15, 8-19, 8-21, 8-22
ClipboardSuccess, 8-6, 8-8, 8-9, 8-11, 8-11,
8-13, 8-14,8-15,8-17,8-18,8-19,
8-21,8-22,8-23,8-25,8-25,8-26
ClipboardTruncate, 8-15, 8-21
command window
command line entry, 6-31
command line history, 6-31
command line recall, 6-31
command window widget
geometry management, 6-31
resizing, 6-31
common attributes, 1-5t, 1-6
definition, 1-4
description, 1-6
DwtHelpCreate, 6-5, A-20
DwtLabelCreate, 3-16, A-23
DwtListBoxCreate, 5-66, A-26

A-33
DwtOptionMenuCreate, 4-24, A-37
DwtPullDownMenuEntryCreate, 4-19, A-39
DwtPushButtonCreate, 3-34, A-42
DwtRadioBoxCreate, 3-29, A-45
DwtScaleCreate, 3-42, A-47
DwtScrollBarCreate, 3-8, A-49
DwtScrollWindowCreate, 2-20, A-51
DwtSeparatorCreate, 4-29, A-54
DwtToggleButtonCreate, 3-22, A-59
DwtWindowCreate, 2-16, A-62
composite widget
dialog box, 5-4, 8
list box, 5-62
main window, 2-3
menu, 4-4
menu bar, 2-9
option menu, 4-22
radio box, 3-27
compound string function
DwtAddFontList, 9-2

compound string function (cont.)
DwtCreateFontList, 9-1
DwtCSbytecmp, 9-4
DwtCSempty,9-5
DwtCSString, 9-2
DwtCStrcat,9-5
DwtCStrcpy,9-6
DwtCStrlen, 9-7
DwtCStrncat, 9-5
DwtCStrncpy,9-6
DwtGetNextSegment, 9-7
DwtInitGetSegment, 9-8
DwtLatinlString, 9-4
DwtString, 9-3
DwtStringFreeContext, 9-9
DwtStringInitContext, 9-9
convenience function
DwtActivateWidget, 10-7
DwtDisplayCSMessage, 10-3
DwtDisplayVmsMessage, 10-2
DwtGetUserData, 10-7
DwtResolvePartOffsets, 10-5
core attributes, 1-5t
definition, 1-4
description, 1-6
DwtAttachedDBCreate, 5-18, A-I
DwtAttachedDBPopupCreate, 5-18, A-I
DwtCautionBoxCreate, 6-27, A-5
DwtColorMixCreate, 5-52, A-7
DwtCommandWindowCreate, 6-32, A-II
DwtCSTextCreate, 5-40, A-13
DwtDialogBoxCreate, 5-7, A-15
DwtDialogBoxPopupCreate, 5-7, A-15
DwtFileSelectionCreate, 6-47, A-17
DwtHelpCreate, 6-5, A-20
DwtLabelCreate, 3-15, A-23
DwtListBoxCreate, 5-65, A-25
DwtMainWindowCreate, 2-6, A-27
DwtMenuBarCreate, 2-11, A-28
DwtMenuCreate, 4-7, A-30
DwtMenuPopupCreate, 4-8, A-32
DwtMenuPulldownCreate, 4-8, A-32
DwtMessageBoxCreate, 6-20, A-35

Index-2

core attributes (cont.)
DwtOptionMenuCreate, 4-23, A-37
DwtPullDownMenuEntryCreate, 4-18, A-39
DwtPushButtonCreate, 3-33, A-42
DwtRadioBoxCreate, 3-28, A-45
DwtScaleCreate, 3-41, A-47
DwtScrollBarCreate, 3-7, A-48
DwtScrollWindowCreate, 2-19, A-50
DwtSelectionCreate, 6-40, A-51
DwtSeparatorCreate, 4-28, A-54
DwtSTextCreate, 5-29, A-56
DwtToggleButtonCreate, 3-21, A-58
DwtWindowCreate, 2-15, A-61
DwtWorkBoxCreate, 6-15, A-63
cut and paste function
callback, 8-6, 8-8
DwtBeginCopyToClipboard, 8-7
DwtCancelCopyFormat, 8-9
DwtCancelCopyToClipboard, 8-9
DwtClipboardLock, 8-10
DwtClipboardRegisterFormat, 8-26
DwtClipboardUnlock, 8-11
DwtCopyFromClipboard, 8-14
DwtCopyToClipboard, 8-16
DwtEndCopyFromClipboard, 8-14
DwtEndCopyToClipboard, 8-18
DwtInquireNextPasteCount, 8-19
DwtInquireNextPasteFormat, 8-20
DwtInquireNextPasteLength,8-21
DwtListPendingItems, 8-23
DwtReCopyToClipboard,8-24
DwtStartCopyFromClipboard, 8-12
DwtStartCopyToClipboard, 8-5
DwtUndoCopyToClipboard, 8-25

D
definition
caution box, 6-23, 6-25
command window, 6-29
control, 3-1
dialog box, 5-1

definition (cont.)
list box, 5-60
menu, 4-1
menu name, 4-1
message box, 6-17
modal dialog box, 5-2
modeless dialog box, 5-2
pop-up menu, 4-1
pull-down menu, 4-1
push button, 3-30
scale, 3-37
scroll bar, 3-1
scroll region, 3-1
slider, 3-1
stepping arrows, 3-1
subarea, 3-1
submenu, 4-1
work-in-progress box, 6-12
dialog box member
message box widget, 6-19, 13
dialog box widget
container, ~, 8
dialog pop-up attributes
DwtCautionBoxCreate, 6-27, A-5
DwtColorMixCreate, 5-53, A-7
DwtCommandWindowCreate, 6-33, A-II
DwtFileSelectionCreate, 6-48, A-18
DwtMessageBoxCreate, 6-21, A-35
DwtSelectionCreate, 6-41, A-52
DwtWorkBoxCreate, 6-15, A-63
directory search function, 6-51
DwtActivateWidget
definition, 10-7
description, 10-7
DwtAddFontList
definition, 9-2
description, 9-2
DwtAnyCailbackStruct
structure declaration, 2-3, 3-14, 3-32, 4-17,

5-5,5-17,5-28,6-4,6-14,6-19,
6-26, 7-4, 7-7, 7-15
DwtAppl.h
include file, 1-8

DwtAttachAdb, 5-23, 5-23,5-24,5-25
DwtAttachedDB
definition, 5-14
description, 5-15
DwtAttachedDBCreate
core attributes, 5-18, A-I
definition, 5-15
description, 5-15
widget-specific attributes, 5-21, 5-21, A-4
DwtAttachedDBPopupCreate
core attributes, 5-18, A-I
definition, 5-15
description, 5-15
widget-specific attributes, 5-21, 5-21, A-4
DwtAttachNone, 5-23, 5-23, 5-24, 5-25
DwtAttachOppAdb, 5-23, 5-23, 5-24, 5-25
DwtAttachOppWidget, 5-23, 5-23, 5-24, 5-25
DwtAttachPosition, 5-23, 5-23, 5-24, 5-25
DwtAttachSelf, 5-23, 5-23, 5-24, 5-25
DwtAttachWidget, 5-23, 5-23, 5-24, 5-25
DwtBeginCopyToClipboard
definition, 8-7
description, 8-7
DwtCallback
structure declaration, 1-9
DwtCallbackPtr
structure declaration, 1-9
DwtCancelCopyFormat
definition, 8-9
description, 8-9
DwtCanceICopyToCIipboard
definition, 8-9
description, 8-10
DwtCautionBox
definition, 6-23
description, 6-25
DwtCautionBoxCreate
core attributes, 6-27, A-5
definition, 6-25
description, 6-25
dialog pop-up attributes, 6-27, A-5
widget-specific attributes, 6-28, A-6

Index-3

DwtClipboardLock
definition, 8-10
description, 8-10
DwtClipboardRegisterFormat
definition, 8-26
description, 8-26
DwtClipboardUnlock
definition, 8-11
description, 8-11
DwtColorMixCallbackStruct
structure declaration, 5-51
DwtColorMixCreate
core attributes, 5-52, A-7
definition, 5-49
dialog pop-up attributes, 5-53, A-7
inherited attributes, 5-53, A-7
widget-specific attributes, 5-54, A-8
DwtColorMixGetNewColor
definition, 5-59
description, 5-59
DwtColorMixSetNewColor
definition, 5-60
description, 5-60
DwtCommandAppend
command line, 6-35
definition, 6-35
description, 6-35
DwtCommandErrorMessage
command line, 6-36
definition, 6-35
description, 6-36
DwtCommandSet
command line, 6-36
definition, 6-36
description, 6-36
DwtCommandWindow
definition, 6-30
description, 6-31
DwtCommandWindowCallbackStruct
structure declaration, 6-31
DwtCommandWindowCreate
core attributes, 6-32, A-II
definition, 6-30

Index-4

DwtCommandWindowCreate (cont.)
description, 6-31
dialog pop-up attributes, 6-33, A-II
widget-specific attributes, 6-34, A-12
DwtCopyFromClipboard
definition, 8-14
description, 8-15
DwtCopyToClipboard
definition, 8--16
description, 8-17
DwtCRActivate
meaning for color mixing widget, 5-51
meaning for file selection box widget, 6-46
meaning for menu bar widget, 2-10, 4--5
meaning for option menu widget, 4--22
meaning for pull-down menu entry gadget,
7-16
meaning for pull-down menu widget, 4--17
meaning for push button gadget, 7-7
meaning for push button widget, 3-32
meaning for selection box widget, 6-39
DwtCRApply
meaning for color mixing widget, 5-51
DwtCRArm
meaning for push button widget, 3-32
meaning for toggle button widget, 3-20
DwtCRCancel
meaning for caution box widget, 6-26
meaning for color mixing widget, 5-51
meaning for file selection box widget, 6-46
meaning for selection box widget, 6-39
meaning for work-in-progress box widget,

6-14
DwtCRCommandEntered
meaning for command window widget, 6-31
DwtCRDisarm
meaning for push button widget, 3-32
meaning for scale widget, 3-40
meaning for toggle button widget, 3-20
DwtCRDrag
meaning for scale widget, 3-40
meaning for scroll bar widget, 3-6

DwtCreateFontList
definition, 9-1
description, 9-1
DwtCRExpose
meaning for window widget, 2-14
DwtCRExtend
meaning for list box widget, 5-63
DwtCRExtendConfirm
meaning for list box widget, 5-63
DwtCRFocus
meaning for caution box widget, 6-26
meaning for command window widget, 6-31
meaning for compound-string text widget,

5-39
meaning for dialog box widget, 5-5
meaning for main window widget, 2-3
meaning for message box widget, 6-19
meaning for pop-up dialog box widget, 5-6
meaning for simple text widget, 5-29
meaning for work-in-progress box widget,

6-14
DwtCRHelpRequested
meaning for attached dialog box widget,

5-17
meaning for caution box widget, 6-26
meaning for command window widget, 6-31
meaning for compound-string text widget,

5-39
meaning for dialog box widget, 5-5
meaning for file selection box widget, 6-46
meaning for help widget, 3-14
meaning for label gadget, 7-4
meaning for list box widget, 5-63
meaning for main window widget, 2-3
meaning for menu bar widget, 2-10, 4-5
meaning for message box widget, 6-19
meaning for option menu widget, 4-22
meaning for pop-up dialog box widget, 5-6
meaning for pull-down menu entry gadget,

7-16
meaning for pull-down menu widget, 4-17
meaning for push button gadget, 7-7
meaning for push button widget, 3-32

DwtCRHelpRequested (cont.)
meaning for radio box widget, 3-27
meaning for scale widget, 3-40
meaning for scroll bar widget, 3-6
meaning for selection box widget, 6-39
meaning for simple text widget, 5-29
meaning for toggle button gadget, 7-12
meaning for toggle button widget, 3-20
meaning for work-in-progress box widget,

6-14
DwtCRLostFocus
meaning for compound-string text widget,

5-39
meaning for simple text widget, 5-29
DwtCRMap
meaning for attached dialog box widget,

5-17
meaning for menu bar widget, 2-10, 4-5
meaning for pop-up dialog box widget, 5-6
meaning for radio box widget, 3-27
DwtCRNo
meaning for caution box widget, 6-26
DwtCRNoFont
meaning for compound-string text widget,

5-39
DwtCRNoMatch
meaning for selection box widget, 6-39
DwtCRPageDec
meaning for scroll bar widget, 3-6
DwtCRPageInc
meaning for scroll bar widget, 3-6
DwtCRSingle
meaning for list box widget, 5-63
DwtCRSingleConfirm
meaning for list box widget, 5-63
DwtCRToBottom
meaning for scroll bar widget, 3-6
DwtCRToTop
meaning for scroll bar widget, 3-6
DwtCRUnitDec
meaning for scroll bar widget, 3-6
DwtCRUnitInc
meaning for scroll bar widget, 3-6

Index-5

DwtCRUnmap
meaning for help widget, 6-4
meaning for menu bar widget, 2-10,4-5
meaning for pop-up dialog box widget, 5-6
DwtCRValueChanged
meaning for command window widget, 6-31
meaning for compound-string text widget,
5-39
meaning for radio box widget, 3-27
meaning for scale widget, 3-40
meaning for scroll bar widget, 3-6
meaning for simple text widget, 5-29
meaning for toggle button gadget, 7-12
meaning for toggle button widget, 3-20
DwtCRYes
meaning for caution box widget, 6-26
meaning for message box widget, 6-19
DwtCSbytecmp
definition, 9-4
description, 9-5
DwtCSempty
definition, 9-5
description, 9-5
DwtCSString
definition, 9-2
description, 9-3
DwtCSText
definition, 5-38
DwtCSTextCallbackStruct
structure declaration, 5-39
DwtCSTextClearSelection
definition, 5-45
description, 5-46
DwtCSTextCreate
core attributes, 5-40, A-13
definition, 5-38
widget-specific attributes, 5-41, A-14
DwtCSTextGetEditable
definition, 5-48
description, 5-48
DwtCSTextGetMaxLength
definition, 5-47
description, 5-47

Index-6

DwtCSTextGetSelection
definition, 5-46
description, 5-46
DwtCSTextGetString
definition, 5-47
description, 5-47
DwtCSTextReplace
definition, 5-48
description, 5-49
DwtCSTextSetEditable
definition, 5-48
description, 5-48
DwtCSTextSetMaxLength
definition, 5-47
description, 5-48
DwtCSTextSetSelection
definition, 5-46
description, 5-46
DwtCSTextSetString
definition, 5-47
description, 5-47
DwtCStrcat
definition, 9-5
description, 9-6
DwtCStrcpy
definition, 9-6
description, 9-6
DwtCStrlen
definition, 9-7
description, 9-7
DwtCStrncat
definition, 9-5
DwtCStrncpy
definition, 9-6
DwtDialogBox
definition, 5-2
description, 5-4, 8
DwtDialogBoxCreate
core attributes, 5-7, A-15
definition, 5-4
description, 5-4, 8
widget-specific attributes, 5-8,5-20, A-3,
A-I 5

DwtDialogBoxPopupCreate
core attributes, 5-7, A-15
definition, 5-4
description, 5-4, 8
widget-specific attributes, 5-8, 5-9, 5-12,
5-20, A-3, A-15, A-16
DwtDisplayCSMessage, 10-1
definition, 10-3
description, 10-5
DwtDisplayVmsMessage
definition, 10-2
description, 10-3
DwtEndCopyFromClipboard
definition, 8-14
description, 8-14
DwtEndCopyToClipboard
cut and paste function, 8-18
description, 8-18
DwtEndCS, 9-8, 9-8
DwtFail, 9-8, 9-8
DwtFileSelection
definition, 6-43
description, 6-45
DwtFileSelectionCailbackStruct
structure declaration, 6-46
DwtFileSelectionCreate
core attributes, 6-47, A-17
definition, 6-45
description, 6-45
dialog pop-up attributes, 6-48, A-18
selection attributes, 6-49, A-19
widget-specific attributes, 6-49, A-19
DwtFileSelectionDoSearch
definition, 6-51
DwtGetNextSegment
definition, 9-7
description,9-7,9-8,18
DwtGetUserData
definition, 10-7
description, 10-7
DwtHelp
definition, 6-2
description, 6-3

DwtHelpCreate
common attributes, 6-5, A-20
core attributes, 6-5, A-20
definition, 6-3
description, 6-3
widget-specific attributes, 6-6, A-21
DwtInitGetSegment
definition, 9-8
DwtInquireNextPasteCount
definition, 8-19
description, 8-19
DwtInquireNextPasteFormat
definition, 8-20
description, 8-21
DwtInquireNextPasteLength
definition, 8-21
description, 8-22
DwtLabel
description, 3-14
high-level function, 1-11,3-13
DwtLabelCreate
common attributes, 3-16, A-23
core attributes, 3-15, A-23
description, 3-14
low-level function, 1-2,3-14
widget-specific attributes, 3-16, A-24
.DwtLabelGadgetCreate
description, 7-3
gadget function, 7-3
rectangle attributes, 7-5, A-24
widget-specific attributes, 7-5, A-25
DwtLatinlString
definition, 9-4
description, 9-4
DwtListBox
defillition, 5-61
description, 5-62
DwtListBoxAddItem
definition, 5-70
description, 5-70
DwtListBoxCallbackStruct
structure declaration, 5-63

Index-7

DwtListBoxCreate
common attributes, 5-66, A-26
core attributes, 5-65, A-25
definition, 5-62
description, 5-62
widget-specific attributes, 5-66, A-26

DwtListBoxDeleteItem
definition, 5-70
description, 5-70
DwtListBoxDeletePos
definition, 5-70
description, 5-70
DwtListBoxDeselectAllltems
definition, 5-71
description, 5-71
DwtListBoxDeselectltem
definition, 5-71
description, 5-71
DwtListBoxDeselectPos
definition, 5-74
description, 5-74
DwtListBoxItemExists
definition, 5-71
description, 3, 5-71
DwtListBoxSelectltem
definition, 5-72
description, 5-72
DwtListBoxSelectPos
definition, 5-74
description, 5-74
DwtListBoxSetHorizpos
definition, 5-72
descIlption, 5-72
DwtListBoxSetltem
definition, 5-73
description, 5-73
DwtListBoxSetPos
definition, 5-73
description, 5-73
DwtListPendingItems
definition, 8-23
description, 8-23

Index-8

DwtMainSetAreas
definition, 2-21
description, 2-22
DwtMainWindow
definition, 2-2
description, 2-3
DwtMainWindowCreate
common attributes, 2-6, A-28
core attributes, 2-6, A-27
definition, 2-2
description, 2-3
geometry management, 2-5
resizing, 2-5
widget-specific attributes, 2-7, A-28
DwtMenu
definition, 4--2
description, 4-4
geometry management, 4--5

DwtMenuBar
definition, 2-8
description, 2-9
DwtMenuBarCreate
common attributes, 2-11, A-29
core attributes, 2-11, A-28
definition, 2-9
description, 2-9
menu attributes, 2-12, A-29

DwtMenuCallbackStruct
structure declaration, 2-10, 4-5, 4-22
DwtMenuCreate
common attributes, 4--8, 4--9, A-31, A-33
core attributes, 4-7, A-30
definition, 4-4
description, 4-4
resizing, 4-6

DwtMenuPopupCreate
common attributes, 4-8,4-9, A-31, A-33
core attributes, 4--8, A-32
definition, 4-4
description, 4-4
geometry management, 4-5
inherited attributes, 4-9, A-33
resizing, 4-6

DwtMenuPosition
definition, 4--26
description, 4--26
DwtMenuPulldownCreate
common attributes, 4--8, 4--9, A-31, A-33
core attributes, 4--8, A-32
definition, 4--4
description, 4--4
geometry management, 4--5
inherited attributes, 4--9, A-33
resizing, 4--6
DwtMessageBox
definition, 6-17
description,6-19,13
DwtMessageBoxCreate
core attributes, 6-20, A-35
definition, 6-18
description, 6-19, 13
dialog pop-up attributes, 6-21, A-35
widget-specific attributes, 6-22, A-36
DwtNaboutLabel, 6-7
DwtNaccelerators, 1-7
DwtNacceleratorText, 3-24, 3-36, 7-8, 7-14
DwtNacceptFocus, 2-7
DwtNactivateCallback, 3-36, 4--20, 6-42, 7-8,
7-17
DwtNadbBottomAttachment, 5-23
DwtNadbBottomOffset, 5-27
DwtNadbBottomPosition, 5-26
DwtNadbBottomWidget, 5-26
DwtNadbLeftAttachment, 5-24
DwtNadbLeftOffset, 5-27
DwtNadbLeftPosition, 5-26
DwtNadbLeftWidget, 5-26
DwtNadbRightAttachment, 5-25
DwtNadbRightOffset, 5-27
DwtNadbRightPosition, 5-26
DwtNadbRightWidget, 5-26
DwtNadbTopAttachment, 5-22
DwtNadbTopOffset, 5-26
DwtNadbTopWidget, 5-25
DwtNaddtopicLabel, 6-8

DwtNadjustMargin, 4--11
DwtNalignment, 3-17, 7-5
DwtNancestorSensitive, 1-7
DwtNapplicationName, 6-8
DwtNapplyCallback, 5-58
DwtNapplyLabel, 5-57, 6-50
DwtNarmCallback, 3-24, 3-36
DwtNautoShowlnsertPoint, 5-32, 5-43
DwtNautoUnmanage, 5-12
DwtNautoUnrealize, 5-12, 7
DwtNbackBlueValue, 5-58
DwtNbackGreenValue, ~-58
DwtNbackground,l-6
DwtNbackgroundPixmap, 1-6
DwtNbackRedValue, 5-58
DwtNbadframeMessage, 6-8
DwtNbadlibMessage, 6-8
DwtNbidirectionalCursor, 5-45
DwtNblinkRate, 5-33, 5-44
DwtNblueLabel, 5-59
DwtNborder, 1-6
DwtNborderPixmap, 1-6
DwtNborderWidth,l-6
DwtNbordHighlight, 3-35
DwtNbuttonAccelerator, 3-24, 3-36, 7-8,
7-14
DwtNcacheHelpLibrary, 6-8,10
DwtNcanceIButton, 5-12
DwtNcancelCallback, 5-58,6-17,6-29,6-42
DwtNcancelLabel, 5-58, 6-17, 6-29, 6-42
DwtNchangeVisAtts, 4-14, 11
DwtNchiidOverlap, 5-11
DwtNcloseLabel, 6-8, 10
DwtNcolormap, 1-7
DwtNcols, 5-31, 5-42, 6-8
DwtNcommandEnteredCaIlback, 6-34
DwtNcommandWindow, 2-7
DwtNconformToText, 3-17
DwtNcopyLabel, 6-8
DwtNdecimaiPoints, 3-43
DwtNdefaultButton, 5-12
DwtNdefaultHorizontalOffset, 5-21

Index-9

DwtNdefaultPosition, 5-10, 6-8, 7
DwtNdefaultPushbutton, 6-29
DwtNdefaultVerticalOft'set, 5-22
DwtNdepth, 1-7
DwtNdestroyCallback, 1-7,5
DwtNdirectionRToL, 1-8,5-9,5-44,6,7-5
DwtNdirMask, 6-50
DwtNdirSpec, 6-50
DwtNdisannCailback, 3-24, 3-36
DwtNdismissLabel,6-8
DwtNdisplayColWinHeight, 5-58
DwtNdisplayColWinWidth, 5-58
DwtNdisplayLabel,5-56
DwtNdisplayWindow, 5-56
DwtNdispWinMargin, 5-58
DwtNdragCailback, 3-10,3-43
DwtNeditable, 5-32, 5-43
DwtNeditingPath, 5-44
DwtNeditLabel, 6-8
DwtNentryAlignment, 4-12
DwtNentryBorder, 4-12
DwtNentryCallback, 4-14
DwtNerroropenMessage, 6-8
DwtNexitLabel, 6-8
DwtNexposeCallback, 2-17
DwtNextendCallback, 5-69
DwtNextendConfirmCallback, 5-69
DwtNfileLabel, 6-8
DwtNfileSearchProc, 6-50
DwtNfileToExternProc, 6-51, 8
DwtNfileTolnternProc, 6-51, 8
DwtNfillHighlight, 3-35
DwtNfilterLabel, 6-50
DwtNfirstTopic,6-9
DwtNfocusCallback, 2-8, 5-10, 5-32, 5-43
DwtNfont, 1-8,5-10,5-33,5-44
DwtNfontX, 5-13
DwtNfontY, 5-13
DwtNforeground, 1-8, 5-9, 5-33, 5-44
DwtNfradionBase, 5-22
DwtNglossaryLabel,6-9
DwtNglossaryTopic,6-9

Index-10

DwtNgobackLabel, 6-9, 9
DwtNgobacktopicLabel, 6-9, 10
DwtNgooverLabel, 6-9
DwtNgotoLabel, 6-9, 9
DwtNgototopicLabel, 6-9, 10
DwtNgrabKeySyms, 5-11
DwtNgrabMergeTranslations, 5-12
DwtNgreenLabel, 5-59
DwtNhaimorder, 5-33, 5-44
DwtNheight, 1-6
DwtNhelpAcknowledgeLabel,6-9,10
DwtNhelpCailback, 1-8,5-10,5-32,5-43,
7-6
DwtNhelpFont, 6-9
DwtNhelphelpLabel, 6-9, 10
DwtNhelpLabel, 6-9
DwtNhelpOnHelpTitle,6-9,10
DwtNhelpontitleLabel, 6-9, 11
DwtNhelptitleLabel, 6-10, 11
DwtNhighlight, 1-8,5-9
DwtNhighlightPixmap, 1-8,5-9
DwtNhistory, 6-34
DwtNhistoryboxLabel, 6-10
DwtNhistoryLabel, 6-10
DwtNhorizontal, 5-68
DwtNhorizontaiScrollBar, 2-7, 2-20
DwtNhotSpotPixmap, 4-20
DwtNiconPixmap, 6-23,13
DwtNinc, 3-9
DwtNindicator, 3-24
DwtNinsensitivePixmap, 3-36, 14
DwtNinsensitivePixmapOft', 3-25, 15
DwtNinsensitivePixmapOn, 3-24, 15
DwtNinsertionPointVisible, 5-32, 5-43
DwtNinsertionPosition, 5-33, 5-43
DwtNitems, 5-67, 6-43
DwtNitemsCount, 5-67, 6-43
DwtNkeywordLabel, 6-10
DwtNkeywordsLabel, 6-10
DwtNlabel, 3-17, 4-25, 6-17, 6-22, 6-29,
6-42, 7-5, 7-8
DwtNlabelAligntnent, 6-23, 13

DwtNlabelType, 3-17
DwtNlibrarySpec, 6-10
DwtNlibraryType, 6-10
DwtNlines, 6-34
DwtNlistUpdated,6-51
DwtNlostFocusCallback, 5-32, 5-43
DwtNmainLabel, 5-56
DwtNmapCallback, 4-15,5-12,6-10, 11, 12
DwtNmappedWbenManaged, 1-7
DwtNmarginBottom, 3-17
DwtNmarginHeight, 3-17, 4-11, 5-10, 5-31,
5-42,5-67
DwtNmarginLeft, 3-17,4-12
DwtNmarginRight, 3-17
DwtNmarginTop, 3-17, 3-17
DwtNmarginWidth, 3-17, 3-17, 3-17,4-11,
4-11,5-10,5-31,5-42,5-67
DwtNmaskToExternProc, 6-51, 8
DwtNmaskToInternProc, 6-51,9
DwtNmatchColors, 5-58
DwtNmaxLength, 5-32, 5-43
DwtNmaxValue, 3-9, 3-43
DwtNmenuAlignment, 4-12
DwtNmenuBar, 2-7
DwtNmenuEntryClass, 4-14
DwtNmenuExtendLastRow, 4-14, 11
DwtNmenuHelpWidget, 4-14
DwtNmenuHistory, 4-14
DwtNmenuIsHomogeneous, 4-13
DwtNmenuNumColumns, 4-13
DwtNmenuPacking, 4-12
DwtNmenuRadio, 4-13
DwtNminValue, 3-9, 3-43
DwtNmixerLabel,5-56
DwtNmixerWindow, 5-57
DwtNmustMatch, 6-43
meaning for selection box widget, 6-39
DwtNnewBlueValue, 5-56
DwtNnewGreenValue, 5-56
DwtNnewRedValue, 5-56
DwtNnoCallback, 6-29
DwtNnofontCallback, 5-45

DwtNnokeywordMessage, 6-10
DwtNnoLabel,6-29
DwtNnoMatchCallback, 6-42
DwtNnoResize, 5-12
DwtNnotitleMessage, 6-10
DwtNnulllibMessage, 6-10
DwtNokCallback,5-58
DwtNokLabel, 5-57, 6-22, 6-42
DwtNorientation, 3-9, 3-43,4-11,4-30, 7-11
DwtNorigBlueValue, 5-56
DwtNorigGreenValue, 5-56
DwtNorigRedValue, 5-56
DwtNoverviewTopic, 6-10
DwtNpageDecCallback, 3-10
DwtNpageInc, 3-9
DwtNpageIncCallback, 3-10
DwtNpendingDelete, 5-33, 5-44
DwtNpixmap, 3-17
DwtNpixmapOff, 3-24
DwtNpixmapOn, 3-24
DwtNprompt, 6-34
DwtNpullingCallback, 4-20, 7-17
DwtNradioAlwaysOne, 4-13
DwtNredLabel,5-59
DwtNresetLabel, 5-57
DwtNresizable, 5, 5-27
DwtNresize, 5-11, 5-68
DwtNresizeHeight, 5-32, 5-42
DwtNresizeWidth, 5-32, 5-42
DwtNrows, 5-31, 5-42, 6-10
DwtNrubberPositioning, 5-22
DwtNsaveasLabel,6-10
DwtNscaleHeight, 3-43
DwtNscaleWidth,3-43
DwtNscreen, 1-7
DwtNscrollLeftSide, 5-33, 5-44
DwtNscrollVertical, 5-31,5-42
DwtNsearchapplyLabel, 6-10
DwtNsearchkeywordboxLabel, 6-11
DwtNsearchLabel, 6-11
DwtNsearchtitleboxLabel, 6-11
DwtNsecondLabel, 6-23, 13

Index-11

DwtNsecondLabelAlignment, 6-23, 13
DwtNselectallLabel, 6-11
DwtNselectedltems, 5-67
DwtNselectedltemsCount, 5-67
DwtNselectionLabel, 6-42
DwtNsensitive, 1-7
DwtNsetNewColorProc, 5-57
DwtNshadow, 3-35
DwtNshape, 3-23,7-14
DwtNshowArrows, 3-11, 14
DwtNshown, 3-9
DwtNshownValueAutomaticHoriz, 2-21
DwtNshownValueAutomaticVert, 2-21
DwtNshowValue, 3-43
DwtNsingleCallback, 5-68
DwtNsingleConfirmCallback, 5-69
DwtNsingleSelection, 563, 5-68
DwtNsliderLabel, 5-59
DwtNspacing, 3-23, 4-11, 5-67
DwtNstyle, 5-10
DwtNsub~enuld,4-20,4-25, 7-17
DwtNtakeFocus, 5-12
DwtNtext~ergeTranslations, 5-10
DwtNtextPath, 5-44
DwtNtitle, 3-43, 5-12
DwtNtitleLabel, 6-11
DwtNtitlesLabel, 6-11
DwtNtitleType, 3-42
DwtNtoBottomCallback, 3-10
DwtNtopictitlesLabel, 6-11
DwtNtopPosition, 5-26, 5-31, 5-42
DwtNtoTopCallback,3-10
DwtNtranslations, 1-7
DwtNtranslationsl, 3-9
DwtNtranslations2, 3-9
DwtNtTranslation, 6-35
DwtNunitDecCailback, 3-10
DwtNunitlncCailback,3-10
DwtNunits, 5-10
DwtNunmapCailback, 4-15, 5-12, 6-11,12
DwtNuserData, 1-8,5-9,5-33, 14
DwtNvaiue, 3-9, 3-24, 3-42, 5-32, 5-43, 6-34,
6-42, 7-14

Index-12

DwtNvalueChangedCailback, 3-10, 3-24,
3-43,5-32,5-43,6-34,7-14
DwtNvalueLabel, 5-59
DwtNverticalScrollBar, 2-7, 2-20
DwtNviewLabel,6-11
DwtNvisibleltemsCount, 5-68, 6-43
DwtNvisibleWhenOtf, 3-23, 7-14
DwtNvisitglosLabel, ()""11
DwtNvisitLabel, 6-11, 10
DwtNvisittopicLabel, 6-11, 11
DwtNwidth, 1-6
DwtNwordWrap, 5-31, 5-42
DwtNworkWindow, 2-7, 2-21, 5-57
DwtNx,l-6
DwtNy,l-6
DwtNyesCallback, 6-22, 6-29
DwtNyesLabel, 6-29
DwtOption~enu

definition, 4-20
description, 4-22
DwtOption~enuCreate

common attributes, 4-24, A-37
core attributes, 4-23, A-37
definition, 4-21
description, 4-22
inherited attributes, 4-24, A-38
DwtPullDown~enuEntry

definition, 4-15
description, 4-16
DwtPullDown~enuEntryCreate

common attributes, 4-19, A-39
core attributes, 4-18, A-39
definition, 4-16
description, 4-16
widget-specific attributes, 4-20, 4-20, A-40
DwtPullDownMenuEntryHilite
definition, 4-26
description, 4-26
DwtPullEntryGadgetCreate
description, 7-15
gadget function, 7-15
label attributes, 7-16, A-41
rectangle attributes, 7-16, A-41

DwtPullEntryGadgetCreate (cont.)
widget-specific attributes, 7-17, A-41
DwtPushButton
definition, 3-31
description, 3-32
DwtPushButtonCreate
common attributes, 3-34, A-42
core attributes, 3-33, A-42
definition, 3-31
description, 3...32
label attributes, 3-34, A-43
widget-specific attributes, 3-35, 3-35, A-43
DwtPushButtonGadgetCreate
description, 7-6
gadget function, 7-6
rectangle attributes, 7-7, A-44
widget-specific attributes, 7-8, A-44
DwtRadioBox
definition, 3-26
description, 3-27
DwtRadioBoxCalIbackStruct
structure declaration, 3-27
DwtRadioBoxCreate
common attributes, 3-29, A-45
core attributes, 3-28, A-45
definition, 3-27
description, 3-27
geometry management, 3-27
inherited attributes, 3-29, A-46
menu attributes, 3-29, A-46
DwtReCopyToClipboard
definition, 8-24
description, 8-24
DwtResolvePartOtfsets
definition, 10-5
description, 10-5
DwtScale
definition, 3-37
description, 3-39
DwtScaleCaIlbackStruct
structure declaration, 3-40
DwtScaleCreate
common attributes, 3-42, A-47

DwtScaleCreate (cont.)
core attributes, 3-41, A-47
definition, 3-39
description, 3-39
widget-specific attributes, 3-42, 3-42, A-48
DwtScaleGetSlider
definition, 3-44
description, 3-44
DwtScaleSetSlider
definition, 3-44
description, 3-44
DwtScrolffiar
definition, 3-2
description, 3-5
DwtScrolffiarCallbackStruct
structure declaration, 3-5
DwtScrollBarCreate
common attributes, 3-8, A-49
core attributes, 3-7, A-48
definition, 3-5
description, 3-5
widget-specific attributes, 3-8, A-49
DwtScrollBarGetSIider
definition, 3-11
description, 3-12
DwtScrollBarSetSlider
definition, 3-12
description, 3-12
DwtScrollWindow
definition, 2-17
description, 2-18
DwtScrollWindowCreate
common attributes, 2-20, A-51
core attributes, 2-19, A-50
definition, 2-18
description, 2-18
widget-specific attributes, 2-20, A-51
DwtScrollWindowSetAreas
definition, 2-22
description, 2-23
DwtSelection
definition, 6-36
description, 6-38

Index-13

DwtSelectionCallbackStruct
structure declaration, 6-39
DwtSelectionCreate
core attributes, 6-40, A-51
definition, 6-38
description, 6-38
dialog pop-up attributes, 6-41, A-52
widget-specific attributes, 6-42, A-53
DwtSeparator
definition, 4-26
description, 4-27
DwtSeparatorCreate
common attributes, 4-29, A-54
core attributes, 4-28, A-54
definition, 4-27
description, 4-27
label attributes, 4-29, A-54
widget-specific attributes, 4-30, A-55
DwtSeparatorGadgetCreate
description, 7-9
gadget function, 7-9
rectangle attributes, 7-10, A-55
widget-specific attributes, 7-10, A-56
DwtStartCopyFromClipboard
definition, 8-12
description, 8-12
DwtStartCopyToClipboard
definition, 8-5
description, 8--6
DwtSText
definition, 5-27
description, 5-28,5-38
DwtSTextClearSelection
definition, 5-34
description, 5-34
DwtSTextCreate
core attributes, 5-29, A-56
definition, 5-28
description, 5-28, 5-38
widget-specific attributes, 5-30, A-57
DwtSTextGetEditable
definition, 5-36
description, 5-36

Index-14

DwtSTextGetMaxLength
definition, 5-36
description, 5-36
DwtSTextGetSelection
definition, 5-34
description, 5-34
DwtSTextGetString
definition, 5-35
description, 5-35
DwtSTextReplace
definition, 5-37
description, 5-37
DwtSTextSetEditable
definition, 5-37
description, 5-37
DwtSTextSetMaxLength
definition, 5-36
description, 5-36
DwtSTextSetSelection
definition, 5-34
description, 5-35
DwtSTextSetString
definition, 5-35
description, 5-35
DwtString
definition, 9-3
description, 9-3
DwtStringFreeContext
definition, 9-9
DwtStringInitContext
definition, 9-9
description, 9-9
DwtSuccess, 9-8, 9-8
DwtToggleButton
definition, 3-18
description, 3-19
DwtTogglebuttonCallbackStruct
structure declaration, 3-20, 7-12
DwtToggleButtonCreate
common attributes, 3-22, A-59
core attributes, 3-21, A-58
definition, 3-19
description, 3-19

DwtToggleButtonCreate (cont.)
label attributes, 3-22, A-59
widget-specific attributes, 3-23, A-59
DwtToggleButtonGadgetCreate
description, 7-11
gadget function, 7-11
label attributes, 7-13, A-61
rectangle attributes, 7-13, A-60
widget-specific attributes, 7-13, A-61
DwtToggleButtonGetState
definition, 3-25
description, 3-25
DwtToggleButtonSetState
definition, 3-25
to set toggle button state, 3-25
DwtUndoCopyToClipboard
definition, 8-25
description, 8-25
DwtWidget.h
include file, 1-8
DwtWindow
definition, 2-13
description, 2-14
DwtWindowCallbackStruct
structure declaration, 2-14
DwtWindowCreate
common attributes, 2-16, A-62
core attributes, 2-15, A-61
definition, 2-14
description, 2-14
widget-specific attributes, 2-17, A-62
DwtWorkBox
definition, 6-12
description, 6-13
DwtWorkBoxCreate
core attributes, 6-15, A-63
definition, 6-13
description, 6-13
dialog pop-up attributes, 6-15, A-63
widget-specific attributes, 6-16, A-64

E
enumerated data type
DwtAttachmentType, 5-22

F
False, 9-9
file selection widget
geometry management, 6-46
function definition
DwtEndCopyToClipboard, 8-18

G
gadget
DwtLabelGadgetCreate, 7-1
DwtPushButtonGadgetCreate, 7-1
DwtSeparatorGadgetCreate, 7-1
DwtToggleButtonGadgetCreate, 7-1
label, 7-3, 7-3
pull-down menu entry, 7-14, 7-15
push button, 7-6, 7-fJ
separator, 7-9, 7-9
toggle button, 7-11, 7-11
gadget classes, 7-lt
gadget function
DwtLabelGadgetCreate, 7-3
DwtPullEntryGadgetCreate, 7-15
DwtPushButtonGadgetCreate,7-6
DwtSeparatorGadgetCreate, 7-9
DwtToggleButtonGadgetCreate, 7-11
geometry management
command window widget, 6-31
DwtAttachedDB, 5-17
DwtAttachedDBCreate, 5-17
DwtAttachedDBPopupCreate, 5-17
DwtCSTextCreate, 5-39

Index-15

geometry management (cont.)
DwtDialogBox, 5-6
DwtDialogBoxCreate, 5-6
DwtDialogBoxPopupCreate, 5-6
DwtLabeIGadgetCreate,7-4
DwtListBox, 5-64
DwtListBoxCreate, 5-64
DwtMainWindowCreate, 2-5
DwtMenu, 4-5
DwtMenuPopupCreate, 4-5
DwtMenuPulldownCreate, 4-5
DwtPushButtonGadgetCreate,7-6
DwtRadioBoxCreate, 3-27
DwtSeparatorGadgetCreate, 7-9
DwtSText, 5-28
DwtSTextCreate, 5-28
file selection widget, 6-46
main window widget, 2-4
pull-down menu entry widget, 4-17
push button widget, 3-32
selection widget, 6-38
work-in-progress box widget, 6-14

high-level function (cont.)

DwtCSTextSetEditable, 5-48
DwtCSTextSetMaxLength, 5-47
DwtCSTextSetSelection, 5-46
DwtCSTextSetString,5-47
DwtDialogBox, 5-2
DwtFileSelection, 6-43
DwtFileSelectionDoSearch, 6-51
DwtHelp, 6-2
DwtLabel, 1-11,3-13
DwtListBox, 5-61
DwtListBoxAddltem, 5-70
DwtListBoxDeleteltem, 5-70
DwtListBoxDeletePos, 5-70
DwtListBoxDeselectAllItems, 5-71
DwtListBoxDeselectItem, 5-71
DwtListBoxDeselectPos, 5-74
DwtListBoxltemExists, 5-71
DwtListBoxSelectItem, 5-72
DwtListBoxSelectPos, 5-74

DwtListBoxSetHorizPos, 5-72

high-level function

DwtListBoxSetItem, 5-73

DwtAttachedDB, 5-14

DwtListBoxSetPos, 5-73

DwtCautionBox, 6-23

DwtMainSetAreas, 2-21

DwtColorMixGetNewColor, 5-59, 5-60

DwtMainWindow, 2-2

DwtCommandAppend, 6-35

DwtMenu, 4-2

DwtCommandErrorMessage, 6-35

DwtMenuBar, 2-8

DwtCommandSet, 6-36

DwtMenuPosition, 4-26

DwtCommandWindow, 6-30

DwtMessageBox, 6-17

DwtCSText, 5-38

DwtOptionMenu, 4-20

DwtCSTextClearSelection, 5-45

DwtPullDownMenuEntry, 4-15

DwtCSTextGetEditable, 5-48

DwtPullDownMenuEntryHilite, 4-26

DwtCSTextGetMaxLength, 5-47

DwtPushButton, 3-31

DwtCSTextGetSelection, 5-46

DwtRadioBox, 3-26

DwtCSTextGetString, 5-47

DwtScale, 3-37

DwtCSTextReplace, 5-48

DwtScaleGetSlider,3-44

Index-16

high-level function (cont.)
DwtScaleSetSlider,3-44
DwtScrollBar, 3-2
DwtScrollBarGetSlider, 3-11
DwtScrollBarSetSlider, 3-12
DwtScrollWindow, 2-17
DwtScrollWindowSetAreas, 2-22
DwtSelection, 6-36
DwtSeparator, 4-26
DwtSText, 5-27
DwtSTextClearSelection, 5-34
DwtSTextGetEditable, 5-36
DwtSTextGetMaxLength,5-36
DwtSTextGetSelection, 5-34
DwtSTextGetString, 5-35
DwtSTextReplace, 5-37
DwtSTextSetEditable, 5-37
DwtSTextSetMaxLength, 5-36
DwtSTextSetSelection, 5-34
DwtSTextSetString, 5-35
DwtToggleButton, 3-18
DwtToggleButtonGetState, 3-25
DwtToggleButtonSetState, 3-25
DwtWindow, 2-13
DwtWorkBox, 6-12

K
keeping an entry highlight, 4-26

L
label attributes

DwtPullDownMenuEntryCreate, 4-19, A-40
DwtPullEntryGadgetCreate, 7-16, A-41
DwtPushButtonCreate, 3-34, A-43
DwtSeparatorCreate, 4-29, A-54
DwtToggleButtonCreate, 3-22, A-59
DwtToggleButtonGadgetCreate, 7-13, A-61
low-level function

DwtAttachedDBCreate, 5-15
DwtAttachedDBPopupCreate,5-15
DwtCautionBoxCreate, 6-25
DwtColorMixCreate, 5-49
DwtCommandWindowCreate, 6-30
DwtCSTextCreate, 5-38
DwtDialogBoxCreate, 5-4
DwtDialogBoxPopupCreate, 5-4
DwtFileSelectionCreate, 6-45
DwtHelpCreate,6-3
DwtLabelCreate, 1-2,3-14

include file

DwtListBoxCreate, 5-62

DwtAppl.h, 1-8

DwtMainWindowCreate, 2-2

DwtWidget.h, 1-8

DwtMenuBarCreate, 2-9

Xlib.h,1-8

DwtMenuCreate, 4-4

inherited attributes

DwtMenuPopupCreate, 4-4

DwtColorMixCreate, 5-53, A-7

DwtMenuPulldownCreate, 4-4

DwtListBoxCreate, 5-66, A-26

DwtMessageBoxCreate, 6-18

DwtMenuPopupCreate, 4-9, A-33

DwtOptionMenuCreate, 4-21

DwtMenuPulldownCreate, 4-9, A-33

DwtPullDownMenuEntryCreate, 4-16

DwtOptionMenuCreate, 4-24, A-38

DwtPushButtonCreate, 3-31

DwtRadioBoxCreate, 3-29, A-46

DwtRadioBoxCreate, 3-27
DwtScaleCreate, 3-39

Index-17

low-level function (cont.)
DwtScrollBarCreate, 3-5
DwtScrollWindowCreate, 2-18
DwtSelectionCreate, 6-38
DwtSeparatorCreate, 4-27
DwtSTextCreate, 5-28
DwtToggleButtonCreate, 3-19
DwtWindowCreate, 2-14
DwtWorkBoxCreate, 6-13

R
rectangle attributes
DwtLabelGadgetCreate, 7-5, A-24
DwtPullEntryGadgetCreate, 7-16, A-41
DwtPushButtonGadgetCreate, 7-7, A-44
DwtSeparatorGadgetCreate, 7-10, A-55
DwtToggleButtonGadgetCreate, 7-13, A-60
resizing
command window widget, 6-31

DwtCSTextCreate, 5-39

main window widget

DwtDialogBox, 5-6

geometry management, 2-4

DwtDialogBoxCreate, 5-6
DwtDialogBoxPopupCreate, 5-6

menu attributes
DwtMenuBarCreate, 2-12, A-29

DwtLabelGadgetCreate, 7-4

DwtRadioBoxCreate, 3-29, A-46

DwtListBox, 5-64

message box widget

DwtListBoxCreate, 5-64

dialog box member, 6-19, 13

DwtMainWindowCreate, 2-5

message function

DwtMenuCreate, 4-6

DwtDisplayCSMessage, 10-3

DwtMenuPopupCreate, 4-6

DwtDisplayVmsMessage, 10-2

DwtMenuPulldownCreate, 4-6
DwtPushButtonGadgetCreate, 7-6

DwtSeparatorGadgetCreate, 7-9

positioning the menu, 4-25

DwtToggleButton, 3-20

primitive widget

DwtToggleButtonCreate, 3-20

push button, 3-32

DwtToggleButtonGadgetCreate, 7-11

scale, 3-39

push button widget, 3-32

pull-down menu entry widget
geometry management, 4-17

hotspot, 4-17

scale widget

label,4-17

slider, 3-39

push button widget

scroll region, 3-13

geometry management, 3-32
resizing, 3-32

selection attributes
DwtFileSelectionCreate, 6-49, A-19
selection widget
geometry management, 6-38

Index-18

slider bar, 3-13
stepping arrow, 3-13
stepping arrows, 3-5
structure declaration
DwtAnyCallbackStruct, 2-3, 3-14, 3-32,
4-17,5-5,5-17,5-28,6-4,6-14,
6-19,6-26,7-4,7-7,7-15
DwtCallback, 1-9
DwtCallbackPtr, 1-9
DwtColorMixCallbackStruct, 5-51
DwtCommandWindowCallbackStruct, 6-31
DwtCSTextCallbackStruct, 5-39
DwtFileSelectionCallbackStruct, 6-46
DwtListBoxCallbackStruct, 5--63
DwtMenuCallbackStruct, 2-10,4-5,4-22
DwtRadioBoxCallbackStruct, 3-27
DwtScaleCallbackStruct, 3-40
DwtScrollBarCallbackStruct,3-5
DwtSelectionCallbackStruct, 6-39
DwtTogglebuttonCallbackStruct, 3-20, 7-12
DwtWindowCallbackStruct, 2-14

widget (cont.)
list box, 5--60, 5--62,5--69, 5-70
main window, 2-2, 2-3, 4-26, 5-35,6-17
menu, 4-4
menu work area, 4-4
pop-up, 4-4
pull-down, 4-4
menu bar, 2-9, 2-9
menu work area, 4-2
message box, 6-19, 6-19, 13, 13
option menu, 4-20, 4-22
pop-up, 4-2
pop-up attached dialog box, 5-15
pop-up dialog box, 5-4, 8
pull-down, 4-2
pull-down menu entry, 4-15, 4-16
push button, 3-30, 3-32
radio box, 3-26, 3-27, 3-27
scale, 3-37, 3-39, 3-43,3-44,3-44

scroll bar, 3-1, 3-5, 3-5, 3-12, 3-12

True, 563, 6-39,9-9

scroll window, 2-17, 2-18
selection box, 6-36, 6-38

separator, 4-27
simple text, 5-34
text, 5-27,5-28,5-34,5-34,5-35,5-35,

widget
attached dialog box, 5-15

5-36,5-36,5-36,5-37

caution box, 6-23, 6-25

text widget, 5-28, 5-38

color mix, 5-49, 5-59, 5--60
command window, 6-29, 6-31

toggle button, 3-18, 3-19,3-25
window, 2-13, 2-14,2-14

compound string text, 5-37, 5-45,5-46,
5-46,5-46,5-47,5-47,5-47,5-48,

work-in-progress box, 6-13
widget class hierarchy, 1-3f

5-48,5-48

DwtAttachedDB, 5-17,5-18

dialog box, 5-4, 8

DwtAttachedDBCreate, 5-17

file selection, 6-43, 6-45

DwtAttachedDBPopupCreate, 5-18

help menu, 6-1, 6-3

DwtCautionBoxCreate, 6-26

label, 3-13, 3-14

DwtColorMixCreate, 5-52

Index-19

widget class hierarchy (cont)
DwtCommandWindow, 6-32
DwtCommandWindowCreate, 6-32
DwtDialogBoxCreate, 5-6
DwtDialogBoxPopupCreate, 5-6
DwtFileSelectionCreate, 6-47
DwtHelp, 6-4
DwtHelpCreate, 6-4
DwtLabel,3-15
DwtLabelCreate, 3-15
DwtLabelGadgetCreate, 7-4
DwtListBox, 5-65
DwtListBoxCreate, 5-65
DwtMainWindow, 2-5
DwtMainWindowCreate, 2-5
DwtMenu, 4-6
DwtMenuCreate, 4-6
DwtMenuPopupCreate, 4-6
DwtMenuPulldownCreate, 4-6
DwtMessageBox, 6-20
DwtMessageBoxCreate, 6-20
DwtOptionMenu, 4-23
DwtOptionMenuCreate, 4-23
DwtPullDownMenuEntry, 4-18
DwtPullDownMenuEntryCreate, 4-18
DwtPullEntryGadgetCreate, 7-16
DwtPushButton, 3-33
DwtPushButtonCreate, 3-33
DwtPushButtonGadgetCreate, 7-7
DwtScale, 3-41
DwtScaleCreate, 3-41
DwtScrollBar, 3-7
DwtScrollBarCreate, 3-7
DwtSelectionCreate, 6-39
DwtSeparator, 4-28
DwtSeparatorCreate, 4-28
DwtSeparatorGadgetCreate, 7-10
DwtSText, 5-29, 5-40
DwtSTextCreate, 5-29, 5--40
DwtToggleButton, 3-21
DwtToggleButtonCreate, 3-21
DwtToggleButtonGadgetCreate, 7-12
DwtWorkBox, 6-14

widget class hierarchy (cont.)
DwtWorkBoxCreate, 6-14
widget instance creation
DwtOptionMenu, 4-22
widget-specific attributes
DwtAttachedDBCreate, 5-21, 5-21, A--4
DwtAttachedDBPopupCreate, 5-21, 5-21,
A-4
DwtCautionBoxCreate, 6-28, A-6
DwtColorMixCreate, 5-54, A-8
DwtCommandWindowCreate, 6-34, A-12
DwtCSTextCreate, 5-41, A-14
DwtDialogBoxCreate, 5-8, 5-20, A-3, A-15
DwtDialogBoxPopupCreate, 5-8, 5-9, 5-12,
5-20, A-3, A-15, A-16
DwtFileSelectionCreate, 6-49, A-19
DwtHelpCreate, 6-6, A-21
DwtLabelCreate, 3-16, A-24
DwtLabelGadgetCreate, 7-5, A-25
DwtListBoxCreate, 5-66, A-26
DwtMainWindowCreate, 2-7, A-28
DwtMessageBoxCreate, 6-22, A-36
DwtPullDownMenuEntryCreate, 4-20, 4-20,
A--40
DwtPullEntryGadgetCreate, 7-17, A--41
DwtPushButtonCreate, 3-35, 3-35, A--43
DwtPushButtonGadgetCreate, 7-8, A-44
DwtScaleCreate, 3--42, 3-42, A--48
DwtScrollBarCreate, 3-8, A-49
DwtScrollWindowCreate, 2-20, A-51
DwtSelectionCreate, 6-42, A-53
DwtSeparatorCreate, 4-30, A-55
DwtSeparatorGadgetCreate, 7-10, A-56
DwtSTextCreate, 5-30, A-57
DwtToggleButtonCreate, 3-23, A-59
DwtToggleButtonGadgetCreate, 7-13, A-6l
DwtWindowCreate, 2-17, A-62
DwtWorkBoxCreate, 6-16, A-64
window manager
title bar, 2-22
work-in-progress box widget
geometry management, 6-14

x
Xlib.h
include file, 1-8

Index-20

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040
before placing your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a
1200- or 2400-baud modem. If you need assistance using the Electronic Store, call
800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Puerto Rico

809-754-7575

Local Digital Subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02j2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International

Local Digital subsidiary or
approved distributor

Internal l

SSB Order Processing - WM0IE15
or
Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

* For internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader's Comments

ULTRIX Worksystem Software
Guide to the XUI Toolkit:
C Language Binding
AA-MA95B-TE

Please use this postage-paid fonn to comment on this manual. If you require a written reply
to a software problem and are eligible to receive one under Software Perfonnance Report
(SPR) service, submit your comments on an SPR fonn.
Thank you for your assistance.

Please rate this manual:

Excellent

Good

o
o
o
o
o
o
o

o
o
o
o
o
o

Accuracy (software works as manual says)
Completeness (enough infonnation)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find infonnation)

Fair

o
o
o
o
o
o
o
o

Poor

o
o

o
o
o
o
o
o

What would you like to see more/less of?
What do you like best about this manual?
What do you like least about this manual?
Please list errors you have found in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

What version of the software described by this manual are you using?
Nameffitle _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Dept.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Dme ________
Company
Mailing Address
____________ Emrul __________________ Phone

_______________________________________________ :

_Jto~~_~e~=lg~_~~~~~!!ee

No Postage

Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE
Digital Equipment Corporation
Publications Manager
Open Software Publications Group
ZK03-2/Z04
110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

Ilh IIllUd 1IIIIIhilihllllill dill II h1111111 hII
Do Not Tear - Fold Here and Tape

Cut

Along
Dotted

Line

Reader's Comments

ULTRIX Worksystem Software
Guide to the XUI Toolkit:
C Language Binding
AA-MA95B-TE

Please rate this manual:

Excellent

Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

o
o
o
o
o
o
o
o

Good

Fair

Poor

o
o
o
o
o
o
o
o

o
o
o

o
o
o
o
o
o
o
o

o
o
o
o
o

What would you like to see more/less of? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
What do you like best about this manual? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
What do you like least about this manual? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

Please list errors you have found in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

What version of the software described by this manual are you using?
Name/Title _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Dept.
Company _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __ Date _ _ _ __
Mailing Address
_____________ Email ___________ Phone __________

_~_~~_~~=E9~_~~~~~J!~

______________________________________________ :I

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

Digital Equipment Corporation
Publications Manager
Open Software Publications Group
ZK03-2/Z04
110 SPIT BROOK ROAD

NASHUA, NH 03062-9987

1111111111111111111111111111111111111111111111111111
Do Not Tear - Fold Here and Tape

Cut
Along
Dotted
Line