SUPER-UX X Toolkit Programming Manual

Contents

Part 1:  X Toolkit Intrinsics - C Language Interface

Part 2:  Athena Widget Set - C Language Interface

Part 1:  X Toolkit Intrinsics - C Language Interface

Introduction

Authors

Acknowledgments

About This Manual

Chapter 1- Intrinsics and Widgets

1.1. Intrinsics

1.2. Languages

1.3. Procedures and Macros

1.4. Widgets

1.4.1. Core Widgets

1.4.1.1. CoreClassPart Structure

1.4.1.2. CorePart Structure

1.4.1.3. Core Resources

1.4.1.4. CorePart Default Values

1.4.2. Composite Widgets

1.4.2.1 CompositeClassPart Structure

1.4.2.2 CompositePart Structure

1.4.2.3. Composite Resources

1.4.2.4. CompositePart Default Values

1.4.3. Constraint Widgets

1.4.3.1. ConstraintClassPart Structure

1.4.3.2. ConstraintPart Structure

1.4.3.3. Constraint Resources

1.5. Implementation-Specific Types

1.6. Widget Classing

1.6.1. Widget Naming Conventions

1.6.2. Widget Subclassing in Public .h Files

1.6.3. Widget Subclassing in Private .h Files

1.6.4. Widget Subclassing in .c Files

1.6.5. Widget Class and Superclass Look Up

1.6.6. Widget Subclass Verification

1.6.7. Superclass Chaining

1.6.8. Class Initialization: class_initialize and class_part_initialize Procedures

1.6.9. Initializing a Widget Class

1.6.10. Inheritance of Superclass Operations

1.6.11. Invocation of Superclass Operations

1.6.12. Class Extension Records

Chapter 2 - Widget Instantiation

2.1. Initializing the X Toolkit

2.2. Establishing the Locale

2.3. Loading the Resource Database

2.4. Parsing the Command Line

2.5. Creating Widgets

2.5.1. Creating and Merging Argument Lists

2.5.2. Creating a Widget Instance

2.5.3. Creating an Application Shell Instance

2.5.4. Convenience Procedure to Initialize an Application

2.5.5. Widget Instance Allocation: the allocate Procedure

2.5.6. Widget Instance Initialization: the initialize Procedure

2.5.7. Constraint Instance Initialization: the ConstraintClassPart initialize Procedure

2.5.8. Nonwidget Data Initialization: the initialize_hook Procedure

2.6. Realizing Widgets

2.6.1. Widget Instance Window Creation: the realize Procedure

2.6.2. Window Creation Convenience Routine

2.7. Obtaining Window Information from a Widget

2.7.1. Unrealizing Widgets

2.8. Destroying Widgets

2.8.1. Adding and Removing Destroy Callbacks

2.8.2. Dynamic Data Deallocation: the destroy Procedure

2.8.3. Dynamic Constraint Data Deallocation: the ConstraintClassPart destroy Procedure

2.8.4. Widget Instance Deallocation: the deallocate Procedure

2.9. Exiting from an Application

Chapter 3 - Composite Widgets and Their Children

3.1. Addition of Children to a Composite Widget: the insert_child Procedure

3.2. Insertion Order of Children: the insert position Procedure

3.3. Deletion of Children: the delete_child Procedure

3.4. Adding and Removing Children from the Managed Set

3.4.1. Managing Children

3.4.2. Unmanaging Children

3.4.3. Bundling Changes to the Managed Set

3.4.4. Determining If a Widget Is Managed

3.5. Controlling When Widgets Get Mapped

3.6. Constrained Composite Widgets

Chapter 4 - Shell Widgets

4.1 Shell Widget Definitions

4.1.1. ShellClassPart Definitions

4.1.2. ShellPart Definition

4.1.3. Shell Resources

4.1.4. ShellPart Default Values

4.2. Session Participation

4.2.1. Joining a Session

4.2.2. Saving Application State

4.2.2.1. Requesting Interaction

4.2.2.2. Interacting with the User During a Checkpoint

4.2.2.3. Responding to a Shutdown Cancellation

4.2.2.4. Completing a Save

4.2.3. Responding to a Shutdown

4.2.4. Resigning from a Session

Chapter 5 - Pop-Up Widgets

5.1. Pop-Up Widget Types

5.2. Creating a Pop-Up Shell

5.3. Creating Pop-Up Children

5.4. Mapping a Pop-Up Widget

5.5. Unmapping a Pop-Up Widget

Chapter 6 - Geometry Management

6.1. Initiating Geometry Changes

6.2. General Geometry Manager Requests

6.3. Resize Requests

6.4. Potential Geometry Changes

6.5. Child Geometry Management: the geometry_manager Procedure

6.6. Widget Placement and Sizing

6.7. Preferred Geometry

6.8. Size Change Management: the resize Procedure

Chapter 7 - Event Management

7.1. Adding and Deleting Additional Event Sources

7.1.1. Adding and Removing Input Sources

7.1.2. Adding and Removing Blocking Notifications

7.1.3. Adding and Removing Timeouts

7.1.4. Adding and Removing Signal Callbacks

7.2. Constraining Events to a Cascade of Widgets

7.2.1. Requesting Key and Button Grabs

7 3. Focusing Events on a Child

7.3.1. Events for Drawables which are not a Widget's Window

7.4 Querying Event Sources

7.5. Dispatching Events

7.6. The Application Input Loop

7.7. Setting and Checking the Sensitivity State of a Widget

7.8. Adding Background Work Procedures

7.9. X Event Filters

7.9.1. Pointer Motion Compression

7.9.2. Enter/Leave Compression

7.9.3. Exposure Compression

7.10. Widget Exposure and Visibility

7.10.1. Redisplay of a Widget: the expose Procedure

7.10.2. Widget Visibility

7.11. X Event Handlers

7.11.1. Event Handlers that Select Events

7.11.2. Event Handlers that Do Not Select Events

7.11.3. Current Event Mask

7.11.4. Event Handlers for X11 Protocol Extensions

7.12. Using the Intrinsics in a Multi-threaded Environment

7.12.1. Initializing a Multithreaded Intrinsics Application

7.12.2. Locking X Toolkit Data Structures

7.12.2.1. Locking the Application Context

7.12.2.2. Locking the Process

7.12.3. Event Management in a Multi-Threaded Environment

Chapter 8 - Callbacks

8.1. Using Callback Procedure and Callback List Definitions

8.2. Identifying Callback Lists

8.3. Adding Callback Procedures

8.4. Removing Callback Procedures

8.5. Executing Callback Procedures

8.6. Checking the Status of a Callback List

Chapter 9 - Resource Management

9.1. Resource Lists

9.2. Byte Offset Calculations

9.3. Superclass-to-Subclass Chaining of Resource Lists

9.4. Subresources

9.5. Obtaining Application Resources

9.6. Resource Conversions

9.6.1. Predefined Resource Converters

9.6.2. New Resource Converters

9.6.3 Issuing Conversion Warnings

9.6.4. Registering a New Resource Converter

9.6.5. Resource Converter Invocation

9.7. Reading and Writing Widget State

9.7.1. Obtaining Widget State

9.7.1.1. Widget Subpart Resource Data: the get_values_hook Procedure

9.7.1.2. Widget Subpart State

9.7.2. Setting Widget State

9.7.2.1. Widget State: the set_values Procedure

9.7.2.2. Widget State: the set_values_almost Procedure

9.7.2.3. Widget State: the ConstraintClassPart set_values Procedure

9.7.2.4. Widget Subpart State

9.7.2.5. Widget Subpart Resource Data: the set_values_hook Procedure

Chapter 10 - Translation Management

10.1. Action Tables

10.1.1. Action Table Registration

10.1.2. Action Names to Procedure Translations

10.1.3. Action Hook Registration

10.2. Translation Tables

10.2.1. Event Sequences

10.2.2. Action Sequences

10.2.3. Multi-click Time

10.3. Translation Table Management

10.4. Using Accelerators

10.5. KeyCode-to-KeySym Conversions

10.6. Obtaining a KeySym in an Action Procedure

10.7. KeySym-to-KeyCode Conversions

10.8. Registering Button and Key Grabs For Actions

10.9. Invoking Actions Directly

10.10. Obtaining a Widget's Action List

Chapter 11 - Utility Functions

11.1. Determining the Number of Elements in an Array

11.2. Translating Strings to Widget Instances

11.3. Managing Memory Usage

11.4. Sharing Graphics Contexts

11.5. Managing Selections

11.5.1. Setting and Getting the Selection Timeout Value

11.5.2. Using Atomic Transfers

11.5.2.1. Atomic Transfer Procedures

11.5.2.2. Getting the Selection Value

11.5.2.3. Setting the Selection Owner

11.5.3. Using Incremental Transfers

11.5.3.1. Incremental Transfer Procedures

11.5.3.2. Getting the Selection Value Incrementally

11.5.3.3. Setting the Selection Owner for Incremental Transfers

11.5.4. Setting and Retrieving Selection Target Parameters

11.5.5. Generating MULTIPLE Requests

11.5.6. Auxiliary Selection Properties

11.5.7. Retrieving the Most Recent Timestamp

11.5.8. Retrieving the Most Recent Event

11.6. Merging Exposure Events into a Region

11.7. Translating Widget Coordinates

11.8. Translating a Window to a Widget

11.9. Handling Errors

11.10. Setting WM_COLORMAP_WINDOWS

11.11. Finding File Names

11.12. Hooks for External Agents

11.12.1. Hook Object Resources

11.12.2. Querying Open Displays

Chapter 12 - Nonwidget Objects

12.1. Data Structures

12.2. Object Objects

12.2.1. ObjectClassPart Structure

12.2.2. ObjectPart Structure

12.2.3. Object Resources

12.2.4. ObjectPart Default Values

12.2.5. Object Arguments To Intrinsics Routines

12.2.6. Use of Objects

12.3. Rectangle Objects

12.3.1. RectObjClassPart Structure

12.3.2. RectObjPart Structure

12.3.3. RectObj Resources

12.3.4. RectObjPart Default Values

12.3.5.Widget Arguments To Intrinsics Routines

12.3.6. Use of Rectangle Objects

12.4. Undeclared Class

12.5. Widget Arguments To Intrinsics Routines

Chapter 13 - Evolution of The Intrinsics

13.1. Determining Specification Revision Level

13.2. Release 3 to Release 4 Compatibility

13.2.1. Additional Arguments

13.2.2. set_values_almost Procedures

13.2.3. Query Geometry

13.2.4. unrealizeCallback Callback List

13.2.5. Subclasses of WMShell

13.2.6. Resource Type Converters

13.2.7. KeySym Case Conversion Procedure

13.2.8. Nonwidget Objects

13.3. Release 4 to Release 5 Compatibility

13.3.1. baseTranslations Resource

13.3.2. Resource File Search Path

13.3.3. Customization Resource

13.3.4. Per-Screen Resource Database

13.3.5. Internationalization of Applications

13.3.6. Permanently Allocated Strings

13.3.7. Arguments to Existing Functions

13.4. Release 5 to Release 6 Compatibility

13.4.1. Widget Internals

13.4.2. General Application Development

13.4.3. Communication with Window and Session Managers

13.4.4. Geometry Management

13.4.5. Event Management

13.4.6. Resource Management

13.4.7. Translation Management

13.4.8. Selections

13.4.9. External Agent Hooks

Appendix A - Resource File Format

Appendix B - Translation Table Syntax

Appendix C - Compatibility Functions

Appendix D - Intrinsics Error

Appendix E - Defined Strings

Index