diff options
38 files changed, 227 insertions, 116 deletions
diff --git a/man/XtAddEventHandler.man b/man/XtAddEventHandler.man index 6bd89a3..92a4f0c 100644 --- a/man/XtAddEventHandler.man +++ b/man/XtAddEventHandler.man @@ -120,14 +120,16 @@ this does not affect the widget's mask and never causes a call on .B XtInsertEventHandler is identical to .B XtAddEventHandler -with the additional \fIposition\fP argument. if \fIposition\fP is +with the additional \fIposition\fP argument. +If \fIposition\fP is .BR XtListHead , the event handler is registered to that it will be called before any event handlers that were previously registered for the same widget. If \fIposition\fP is .BR XtListTail , the event handler is registered to be called after any previously -registered event handlers. If the procedure is already registered with +registered event handlers. +If the procedure is already registered with the same \fIclient_data\fP value, the specified mask augments the existing mask and the procedure is repositioned in the list. .LP @@ -136,7 +138,8 @@ is similar to .B XtInsertEventHandler except that it does not modify the widget's event mask and never causes an .B XSelectInput -for the specified events. If the procedure is already registered with the +for the specified events. +If the procedure is already registered with the same \fIclient_data\fP value, the specified mask augments the existing mask and the procedure is repositioned in the list. .SH "SEE ALSO" diff --git a/man/XtAllocateGC.man b/man/XtAllocateGC.man index 343f9c5..30eab59 100644 --- a/man/XtAllocateGC.man +++ b/man/XtAllocateGC.man @@ -62,17 +62,20 @@ function returns a sharable GC that may be modified by the client. The \fIscreen\fP field of the specified widget or of the nearest widget ancestor of the specified object and the specified \fIdepth\fP argument supply the root and drawable depths for which the GC is to -be valid. If \fIdepth\fP is zero the depth is taken from the \fIdepth\fP +be valid. +If \fIdepth\fP is zero the depth is taken from the \fIdepth\fP field of the specified widget or of the nearest widget ancestor of the specified object. .LP The \fIvalue_mask\fP argument specifies the fields of the GC that will be initialized with the respective members of the \fIvalues\fP structure. The \fIdynamic_mask\fP argument specifies fields that the caller intends -to modify during program execution. The caller must ensure that the +to modify during program execution. +The caller must ensure that the corresponding GC field is set prior to each use of the GC. The \fIunused_mask\fP argument specifies fields of the GC that are of no -interest to the caller. The caller may make no assumptions about the +interest to the caller. +The caller may make no assumptions about the contents of any fields specified in \fIunused_mask\fP. The caller may assume that at all times all fields not specified in either \fIdynamic_mask\fP or \fIunused_mask\fP have their default value if diff --git a/man/XtAppAddActionHook.man b/man/XtAppAddActionHook.man index 361a815..1f506ae 100644 --- a/man/XtAppAddActionHook.man +++ b/man/XtAppAddActionHook.man @@ -53,7 +53,8 @@ Specifies the application-specific data to be passed to the action hook. .SH DESCRIPTION .B XtAppAddActionHook adds the specified procedure to the front of a list maintained in the -application context. In the future, when an action routine is about to +application context. +In the future, when an action routine is about to be invoked for any widget in this application context, either through the translation manager or via .BR XtCallActionProc , diff --git a/man/XtAppAddConverter.man b/man/XtAppAddConverter.man index 854e9c3..d873b67 100644 --- a/man/XtAppAddConverter.man +++ b/man/XtAppAddConverter.man @@ -66,7 +66,8 @@ is equivalent in function to .B XtAppSetTypeConverter with \fIcache_type\fP equal to .B XtCacheAll -for old-format type converters. It has been superseded by +for old-format type converters. +It has been superseded by .BR XtAppSetTypeConverter . .LP .B XtAddConverter @@ -74,7 +75,8 @@ is equivalent in function to .B XtSetTypeConverter with \fIcache_type\fP equal to .B XtCacheAll -for old-format type converters. It has been superseded by +for old-format type converters. +It has been superseded by .BR XtSetTypeConverter . .SH "SEE ALSO" XtConvert(__libmansuffix__), diff --git a/man/XtAppAddSignal.man b/man/XtAppAddSignal.man index 7854ec0..885682d 100644 --- a/man/XtAppAddSignal.man +++ b/man/XtAppAddSignal.man @@ -62,7 +62,8 @@ raised. The .B XtAppAddSignal function initiates a mechanism for handling signals within the context -of the Intrinsics. Prior to establishing an operating system dependent +of the Intrinsics. +Prior to establishing an operating system dependent signal handler the application may call .B XtAppAddSignal and store the returned \fIid\fP in a place accessible to the signal @@ -76,12 +77,14 @@ passing the \fIid\fP returned by the call to .LP .B XtNoticeSignal is the only Intrinsics function that can safely be called from a signal -handler. If +handler. +If .B XtNoticeSignal is called multiple times before the Intrinsics are able to invoke the -registered callback, the callback is only called once. Logically the -Intrinsics maintain ``pending'' for each registered callback. This -flag is initially +registered callback, the callback is only called once. +Logically the +Intrinsics maintain ``pending'' for each registered callback. +This flag is initially .B False and is set to .B True @@ -95,8 +98,8 @@ just before the callback is invoked. .LP The .B XtRemoveSignal -function is called to remove the specified Intrinsics signal handler. The -client should disable the source of the signal before calling +function is called to remove the specified Intrinsics signal handler. +The client should disable the source of the signal before calling .BR XtRemoveSignal . .SH "SEE ALSO" XtAppAddTimeOut(__libmansuffix__),XtAppAddInput(__libmansuffix__),XtAppAddWorkProc(__libmansuffix__) diff --git a/man/XtAppInitialize.man b/man/XtAppInitialize.man index 79e37f5..c4ab2bf 100644 --- a/man/XtAppInitialize.man +++ b/man/XtAppInitialize.man @@ -91,14 +91,17 @@ finally calls with \fIapplication_name\fP NULL, \fIwidget_class\fP .BR applicationShellWidgetClass , and the specified \fIargs\fP and \fInum_args\fP and returns the -created shell. The modified \fIargc\fP and \fIargv\fP returned by +created shell. +The modified \fIargc\fP and \fIargv\fP returned by .B XtDisplayInitialize are returned in \fIargc_in_out\fP and \fIargv_in_out\fP. If \fIapp_context_return\fP is not NULL, the created application context -is also returned. If the display specified by the command line cannot +is also returned. +If the display specified by the command line cannot be opened, an error message is issued and .B XtAppInitialize -terminates the application. If \fIfallback_resources\fP is non-NULL, +terminates the application. +If \fIfallback_resources\fP is non-NULL, .B XtAppSetFallbackResources is called with the value prior to calling .BR XtOpenDisplay . diff --git a/man/XtAppNextEvent.man b/man/XtAppNextEvent.man index d087c7d..d04b7d7 100644 --- a/man/XtAppNextEvent.man +++ b/man/XtAppNextEvent.man @@ -117,7 +117,8 @@ flushes the output buffer and returns zero. The .B XtAppProcessEvent function processes one timer, alternate input, signal source, or X -event. If there is nothing of the appropriate type to process, +event. +If there is nothing of the appropriate type to process, .B XtAppProcessEvent blocks until there is. If there is more than one type of thing available to process, diff --git a/man/XtAppReleaseCacheRefs.man b/man/XtAppReleaseCacheRefs.man index 5775c03..c217a68 100644 --- a/man/XtAppReleaseCacheRefs.man +++ b/man/XtAppReleaseCacheRefs.man @@ -49,10 +49,11 @@ Specifies the list of cache references to be released. .SH DESCRIPTION .B XtAppReleaseCacheRefs decrements the reference count for the conversion entries identified -by the \fIrefs\fP argument. This argument is a pointer to a NULL-terminated -list of +by the \fIrefs\fP argument. +This argument is a pointer to a NULL-terminated list of .B XtCacheRef -values. If any reference count reaches zero, the destructor, if any, will +values. +If any reference count reaches zero, the destructor, if any, will be called and the resource removed from the conversion cache. .SH "SEE ALSO" .br diff --git a/man/XtAppSetFallbackResources.man b/man/XtAppSetFallbackResources.man index 7730263..25e9872 100644 --- a/man/XtAppSetFallbackResources.man +++ b/man/XtAppSetFallbackResources.man @@ -63,7 +63,8 @@ is not required to copy \fIspecification_list\fP; the caller must ensure that the contents of the list and the strings addressed by the list remain valid until all displays are initialized or until .B XtAppSetFallbackResources -is called again. The value NULL for \fIspecification_list\fP removes +is called again. +The value NULL for \fIspecification_list\fP removes any previous fallback resource specification for the application context. The intended use for fallback resources is to provide a minimal number of resources that will make the application usable (or at least terminate diff --git a/man/XtAppSetTypeConverter.man b/man/XtAppSetTypeConverter.man index 1444319..ee3b7d8 100644 --- a/man/XtAppSetTypeConverter.man +++ b/man/XtAppSetTypeConverter.man @@ -76,7 +76,8 @@ contexts created by the calling process, including any future application contexts that may be created. .B XtAppSetTypeConverter registers the specified type converter in the single application context -specified. If the same \fIfrom_type\fP and \fIto_type\fP are specified +specified. +If the same \fIfrom_type\fP and \fIto_type\fP are specified in multiple calls to either function, the most recent overrides the previous ones. .SH "SEE ALSO" diff --git a/man/XtCallActionProc.man b/man/XtCallActionProc.man index b0a82dd..18ce528 100644 --- a/man/XtCallActionProc.man +++ b/man/XtCallActionProc.man @@ -43,7 +43,8 @@ void XtCallActionProc(Widget \fIwidget\fP, const char *\fIaction\fP, XEvent *\fIevent\fP, String *\fIparams\fP, Cardinal \fInum_params\fP); .SH ARGUMENTS .IP \fIwidget\fP 1i -Specifies the widget in which the action is to be invoked. Must be +Specifies the widget in which the action is to be invoked. +Must be of class core of any subclass thereof. .IP \fIaction\fP 1i Specifies the name of the action routine. @@ -56,12 +57,15 @@ Specifies the num of entries in \fIparams\fP. .SH DESCRIPTION .B XtCallActionProc searches for the named action routine in the same manner and order as -translation tables are bound. If found, the action routine is invoked -with the specified widget, event pointer, and parameters. It is the +translation tables are bound. +If found, the action routine is invoked +with the specified widget, event pointer, and parameters. +It is the responsibility of the caller to ensure that the contents of \fIevent\fP, \fIparams\fP, and \fInum_params\fP arguments are appropriate for the specified routine, and if necessary, that the specified widget is -realized or sensitive. If the named action routine cannot be found, +realized or sensitive. +If the named action routine cannot be found, .B XtCallActionProc generates a warning message and returns. .SH "SEE ALSO" diff --git a/man/XtClass.man b/man/XtClass.man index 8842c55..f23a40e 100644 --- a/man/XtClass.man +++ b/man/XtClass.man @@ -98,9 +98,11 @@ The function returns .B True if the class of the specified widget is equal to or is a subclass of -the specified class. The widget's class can be any number of subclasses +the specified class. +The widget's class can be any number of subclasses down the chain and need not be an immediate subclass of the specified -class. Composite widgets that need to restrict the class of the items +class. +Composite widgets that need to restrict the class of the items they contain can use .B XtIsSubclass to find out if a widget belongs to the desired class of objects. @@ -128,7 +130,8 @@ and generates no code. To test if a given widget belongs to a subclass of an Intrinsics-defined class, the Intrinsics defines macros or functions equivalent to .B XtIsSubclass -for each of the built-in classes. These procedures are +for each of the built-in classes. +These procedures are .BR XtIsObject , .BR XtIsRectObj , .BR XtIsWidget , diff --git a/man/XtConvertAndStore.man b/man/XtConvertAndStore.man index e88263a..717aad7 100644 --- a/man/XtConvertAndStore.man +++ b/man/XtConvertAndStore.man @@ -90,7 +90,8 @@ registered or was registered with cache type or .B XtCacheByDisplay looks in the conversion cache to see if this conversion procedure -has been called with the specified conversion arguments. If so, it +has been called with the specified conversion arguments. +If so, it checks the success status of the prior call, and if the conversion failed, .B XtCallConverter @@ -118,13 +119,15 @@ enters the result into the cache. then returns what the converter returned. .LP The \fIcache_ref_return\fP field specifies storage allocated by the -caller in which an opaque value will be stored. If the type converter +caller in which an opaque value will be stored. +If the type converter has been registered with the .B XtCacheRefCount modifier and if the value returned in in \fIcache_ref_return\fP is non-NULL, then the call should store the \fIcache_ref_return\fP value in order to decrement the reference count when the converted value -is no longer required. The \fIcache_ref_return\fP argument should be +is no longer required. +The \fIcache_ref_return\fP argument should be NULL if the caller is unwilling or unable to store the value. .SH "SEE ALSO" XtAppReleaseCacheRefs(__libmansuffix__) diff --git a/man/XtCreateSelectionRequest.man b/man/XtCreateSelectionRequest.man index c1131fd..ea31ae3 100644 --- a/man/XtCreateSelectionRequest.man +++ b/man/XtCreateSelectionRequest.man @@ -48,7 +48,8 @@ void XtSendSelectionRequest(Widget \fIrequestor\fP, Atom \fIselection\fP, Time void XtCancelSelectionRequest(Widget \fIrequestor\fP, Atom \fIselection\fP); .SH ARGUMENTS .IP \fIrequestor\fP 1i -Specifies the widget making the request. Must be of class Core or a +Specifies the widget making the request. +Must be of class Core or a subclass thereof. .IP \fIselection\fP 1i Specifies the particular selection desired. @@ -64,7 +65,8 @@ and with the requestor and selection as specified to .B XtCreateSelectionRequest will be bundled into a single selection conversion request with -multiple targets. The request is actually initiated by calling +multiple targets. +The request is actually initiated by calling .BR XtSendSelectionRequest . .LP When @@ -73,9 +75,11 @@ is called with a value of \fIrequestor\fP and \fIselection\fP matching a previous call to .BR XtCreateSelectionRequest , a selection conversion request is actually sent to the selection owner. -If a single target request is queued, that request is made. If multiple +If a single target request is queued, that request is made. +If multiple targets are queued they are bundled into a single request with the -target MULTIPLE using the specified timestamp. As the conversions are +target MULTIPLE using the specified timestamp. +As the conversions are made, the callbacks associated with each .B XtGetSelectionValue and @@ -95,7 +99,8 @@ When .B XtCancelSelectionRequest is called, any requests queued since the last call to .B XtCreateSelectionRequest -are cleaned up. Subsequent calls to +are cleaned up. +Subsequent calls to .BR XtGetSelectionValue , .BR XtGetSelectionValues , .BR XtGetSelectionValueIncremental , diff --git a/man/XtDisplayInitialize.man b/man/XtDisplayInitialize.man index 6f94612..f0b6954 100644 --- a/man/XtDisplayInitialize.man +++ b/man/XtDisplayInitialize.man @@ -169,7 +169,8 @@ the results are not defined. The .B XtScreenDatabase function returns the fully merged resource database associated with the -specified screen. If the \fIscreen\fP does not belong to a +specified screen. +If the \fIscreen\fP does not belong to a .B Display initialized by .BR XtDisplayInitialize , diff --git a/man/XtFindFile.man b/man/XtFindFile.man index 905dd42..3a87a9b 100644 --- a/man/XtFindFile.man +++ b/man/XtFindFile.man @@ -52,29 +52,37 @@ Specifies the number of substitutions passed in. Specifies a procedure to call to judge a potential file name, or NULL. .SH DESCRIPTION The \fIpath\fP parameter specifies a string that consists of a series of -potential file names delimited by colons. Within each name, the +potential file names delimited by colons. +Within each name, the percent character specifies a string substitution selected by the -following character. The character sequence ``%:'' specifies an +following character. +The character sequence ``%:'' specifies an embedded colon that is not a delimiter; the sequence is replaced by a -single colon. The character sequence ``%%'' specifies a percent +single colon. +The character sequence ``%%'' specifies a percent character that does not introduce a substitution; the sequence is -replaced by a single percent character. If a percent character is +replaced by a single percent character. +If a percent character is followed by any other character, .B XtFindFile looks through the specified \fIsubstitutions\fP for that character in the \fImatch\fP field and if found replaces the percent and match characters with the string in the -corresponding \fIsubstitution\fP field. A \fIsubstitution\fP field entry of NULL -is equivalent to a pointer to an empty string. If the operating +corresponding \fIsubstitution\fP field. +A \fIsubstitution\fP field entry of NULL +is equivalent to a pointer to an empty string. +If the operating system does not interpret multiple embedded name separators in the path (i.e., ``/'' in POSIX) the same way as a single separator, .B XtFindFile will collapse multiple separators into a single one after performing -all string substitutions. Except for collapsing embedded separators, +all string substitutions. +Except for collapsing embedded separators, the contents of the string substitutions are not interpreted by .B XtFindFile and may therefore contain any operating-system-dependent -characters, including additional name separators. Each resulting +characters, including additional name separators. +Each resulting string is passed to the predicate procedure until a string is found for which the procedure returns .BR True ; diff --git a/man/XtGetActionList.man b/man/XtGetActionList.man index b8f457b..9c62a17 100644 --- a/man/XtGetActionList.man +++ b/man/XtGetActionList.man @@ -50,13 +50,16 @@ Returns the action list. Returns the number of action procedures declared by the class. .SH DESCRIPTION .B XtGetActionList -returns the action table defined by the specified widget class. This -table does not include actions defined by the superclasses. If +returns the action table defined by the specified widget class. +This +table does not include actions defined by the superclasses. +If \fIwidget_class\fP is not initialized, or is not .B coreWidgetClass or a subclass thereof, or if the class does not define any actions, *\fIactions_return\fP will be NULL and *\fInum_actions_return\fP will -be zero. If *\fIactions_return\fP is non-NULL the client is responsible +be zero. +If *\fIactions_return\fP is non-NULL the client is responsible for freeing the table using .B XtFree when it is no longer needed. diff --git a/man/XtGetApplicationNameAndClass.man b/man/XtGetApplicationNameAndClass.man index 7aa8f94..7ce6f8a 100644 --- a/man/XtGetApplicationNameAndClass.man +++ b/man/XtGetApplicationNameAndClass.man @@ -53,8 +53,10 @@ Returns the application class. .B XtGetApplicationNameAndClass returns the application name and class passed to .B XtDisplayInitialize -for the specified display. If the display was never initialized or -has been closed, the result is undefined. The returned strings are +for the specified display. +If the display was never initialized or +has been closed, the result is undefined. +The returned strings are owned by the Intrinsics and must not be modified or freed by the caller. .SH "SEE ALSO" diff --git a/man/XtGetClassExtension.man b/man/XtGetClassExtension.man index 757b616..03132b6 100644 --- a/man/XtGetClassExtension.man +++ b/man/XtGetClassExtension.man @@ -64,7 +64,8 @@ and a record size greater than or equal the specified \fIrecord_size\fP if it is nonzero. .B XtGetClassExtension returns a pointer to a matching extension record or NULL if no match -is found. The returned extension record is owned by the widget class +is found. +The returned extension record is owned by the widget class and must not be modified or freed by the caller, except possibly to be modified by the widget class owner. .SH "SEE ALSO" diff --git a/man/XtGetKeysymTable.man b/man/XtGetKeysymTable.man index 5bbf256..ab276d1 100644 --- a/man/XtGetKeysymTable.man +++ b/man/XtGetKeysymTable.man @@ -67,7 +67,8 @@ Returns the number of KeyCodes in the keycode list. .SH DESCRIPTION .B XtGetKeysymTable returns a pointer to the Intrinsics' copy of the server's KeyCode-to-KeySym -table. This table must not be modified. +table. +This table must not be modified. .LP The .B XtKeysymToKeycodeList diff --git a/man/XtGetResourceList.man b/man/XtGetResourceList.man index 2b5098f..0bedaff 100644 --- a/man/XtGetResourceList.man +++ b/man/XtGetResourceList.man @@ -66,7 +66,8 @@ returns the resource list as specified in the widget class record. If it is called after the widget class has been initialized, .B XtGetResourceList returns a merged resource list that contains the resources -for all superclasses. The list returned by +for all superclasses. +The list returned by .B XtGetResourceList should be freed using .B XtFree @@ -78,13 +79,16 @@ is called before the widget class is initialized (that is, before the first widget of that class has been created), .B XtGetConstraintResourceList returns the resource list as specified in the widget class Constraint -part record. If it is called after the widget class has been initialized, +part record. +If it is called after the widget class has been initialized, .B XtGetConstraintResourceList returns a merged resource list that contains the Constraint resources -for all superclasses. If the specified class is not a subclass of +for all superclasses. +If the specified class is not a subclass of .BR constraintWidgetClass , \fI*resources_return\fP is set to NULL and \fI*num_resources_return\fP -is set to zero. The list returned by +is set to zero. +The list returned by .B XtGetConstraintResourceList should be freed using .B XtFree diff --git a/man/XtGetSelectionParameters.man b/man/XtGetSelectionParameters.man index 74e0f6f..6c22498 100644 --- a/man/XtGetSelectionParameters.man +++ b/man/XtGetSelectionParameters.man @@ -56,7 +56,8 @@ Specifies a pointer to an atom in which the property type of the parameters will be stored. .IP \fIvalue_return\fP 1i Specifies a pointer into which a pointer to the parameters are to be -stored. A NULL will be stored if no parameters accompany the request. +stored. +A NULL will be stored if no parameters accompany the request. .IP \fIlength_return\fP 1i Specifies a pointer into which the number of data elements in \fIvalue_return\fP of size indicated by \fIformat_return\fP will be diff --git a/man/XtGetSelectionRequest.man b/man/XtGetSelectionRequest.man index 2ac673e..50aec3c 100644 --- a/man/XtGetSelectionRequest.man +++ b/man/XtGetSelectionRequest.man @@ -55,9 +55,11 @@ may only be called from within an .B XtConvertSelectionProc procedure and returns a pointer to the .B SelectionRequest -event that caused the conversion procedure to be invoked. \fIRequest_id\fP +event that caused the conversion procedure to be invoked. +\fIRequest_id\fP specifies a unique id for the individual request in the case that -multiple incremental transfers are outstanding. For atomic transfers, +multiple incremental transfers are outstanding. +For atomic transfers, \fIrequest_id\fP must be specified as NULL. If no .B SelectionRequest event is being processed for the specified \fIwidget\fP, \fIselection\fP, diff --git a/man/XtGetSelectionValueIncremental.man b/man/XtGetSelectionValueIncremental.man index f4f8c65..7482d33 100644 --- a/man/XtGetSelectionValueIncremental.man +++ b/man/XtGetSelectionValueIncremental.man @@ -76,13 +76,15 @@ except that the \fIselection_callback\fP procedure will be called repeatedly upon delivery of multiple segments of the selection value. The end of the selection value is indicated when \fIselection_callback\fP is called with a non-NULL value of length zero, which must still be -freed by the client. If the transfer of the selection is aborted in the +freed by the client. +If the transfer of the selection is aborted in the middle of a transfer (for example, because to timeout), the \fIselection_callback\fP procedure is called with a type value equal to the symbolic constant .B XT_CONVERT_FAIL so that the requestor can dispose of the partial selection value it has -collected up until that point. Upon receiving +collected up until that point. +Upon receiving .BR XT_CONVERT_FAIL , the requesting client must determine for itself whether or not a partially completed transfer is meaningful. diff --git a/man/XtGrabKey.man b/man/XtGrabKey.man index 5e8f145..7b97e65 100644 --- a/man/XtGrabKey.man +++ b/man/XtGrabKey.man @@ -67,7 +67,8 @@ int \fIevent_mask\fP, int \fIpointer_mode\fP, int \fIkeyboard_mode\fP, Window void XtUngrabPointer(Widget \fIwidget\fP, Time \fItime\fP); .SH ARGUMENTS .IP \fIwidget\fP 1i -Specifies the widget in whose window the grab will occur. Must be of +Specifies the widget in whose window the grab will occur. +Must be of class Core or a subclass thereof. .sp 6p .IP \fIkeycode\fP @@ -101,12 +102,14 @@ Specifies arguments to the associated Xlib function call. calls .B XGrabKey specifying the widget's window as the grab window if the widget is -realized. The remaining arguments are exactly as for +realized. +The remaining arguments are exactly as for .BR XGrabKey . If the widget is not realized, or is later unrealized, the call to .B XGrabKey will be performed (again) when the widget is realized and its window -becomes mapped. In the future, if +becomes mapped. +In the future, if .B XtDispatchEvent is called with a .B KeyPress @@ -131,7 +134,8 @@ returns calls .B XUngrabKey specifying the widget's window as the ungrab window if the widget is -realized. The remaining arguments are exactly as for +realized. +The remaining arguments are exactly as for .BR XUngrabKey . If the widget is not realized, .B XtUngrabKey @@ -143,7 +147,8 @@ If the specified widget is realized .B XtGrabKeyboard calls .B XGrabKeyboard -specifying the widget's window as the grab window. The remaining +specifying the widget's window as the grab window. +The remaining arguments and return value are exactly as for .BR XGrabKeyboard . If the widget is not realized, @@ -162,12 +167,14 @@ with the specified time. calls .B XGrabButton specifying the widget's window as the grab window if the widget is -realized. The remaining arguments are exactly as for +realized. +The remaining arguments are exactly as for .BR XGrabButton . If the widget is not realized, or is later unrealized, the call to .B XGrabButton will be performed (again) when the widget is realized and its window -becomes mapped. In the future, if +becomes mapped. +In the future, if .B XtDispatchEvent is called with a .B ButtonPress @@ -192,7 +199,8 @@ returns calls .B XUngrabButton specifying the widget's window as the ungrab window if the widget is -realized. The remaining arguments are exactly as for +realized. +The remaining arguments are exactly as for .BR XUngrabButton . If the widget is not realized, .B XtUngrabButton @@ -203,7 +211,8 @@ request, if any, for the specified widget, button, and modifiers. .B XtGrabPointer calls .B XGrabPointer -specifying the widget's window as the grab window. The remaining +specifying the widget's window as the grab window. +The remaining arguments and return value are exactly as for .BR XGrabPointer . If the widget is not realized, diff --git a/man/XtHooksOfDisplay.man b/man/XtHooksOfDisplay.man index a3ed9d4..10380de 100644 --- a/man/XtHooksOfDisplay.man +++ b/man/XtHooksOfDisplay.man @@ -45,7 +45,9 @@ Widget XtHooksOfDisplay(Display* \fIdisplay\fP); Specifies the desired display. .SH DESCRIPTION The class of this object is a private, implementation dependent, subclass -of Object. The hook object has no parent. The resources of this object are +of Object. +The hook object has no parent. +The resources of this object are the callback lists for hooks and the read-only resources for getting a list of parentless shells. .SH "SEE ALSO" diff --git a/man/XtInitialize.man b/man/XtInitialize.man index d7c9bde..fd23c8e 100644 --- a/man/XtInitialize.man +++ b/man/XtInitialize.man @@ -72,9 +72,11 @@ finally calls with \fIapplication_name\fP NULL, \fIwidget_class\fP .BR applicationShellWidgetClass , and the specified \fIargs\fP and \fInum_args\fP and returns the -created shell. The semantics of calling +created shell. +The semantics of calling .B XtInitialize -more than once are undefined. This routine has been replaced by +more than once are undefined. +This routine has been replaced by .BR XtAppInitialize . .SH "SEE ALSO" .BR XtAppInitialize (__libmansuffix__) diff --git a/man/XtInsertEventTypeHandler.man b/man/XtInsertEventTypeHandler.man index 4ec83a1..cfad446 100644 --- a/man/XtInsertEventTypeHandler.man +++ b/man/XtInsertEventTypeHandler.man @@ -96,8 +96,10 @@ If the widget is realized .B XtInsertEventTypeHandler calls .B XSelectInput -if necessary. Specifying NULL for \fIselect_data\fP is equivalent to -specifying a pointer to an event mask containing 0. This is similar to the +if necessary. +Specifying NULL for \fIselect_data\fP is equivalent to +specifying a pointer to an event mask containing 0. +This is similar to the .B XtInsertRawEventHandler function. .LP @@ -111,7 +113,8 @@ as long as the event handler remains registered with this value of \fIselect_data\fP. .LP The \fIposition\fP argument allows the client to control the order of the -invocation of event handlers registered for the same event type. If the +invocation of event handlers registered for the same event type. +If the client does not care about the order, it should normally specify .BR XtListTail , which registers this event handler after any previously registered @@ -121,7 +124,8 @@ The .B XtRemoveEventTypeHandler function unregisters an even handler registered with .B XtInsertEventTypeHandler -for the specified event type. The request is ignored if \fIclient_data\fP +for the specified event type. +The request is ignored if \fIclient_data\fP does not match the value given with the handler was registered. .LP If \fIevent_type\fP specifies on of the core X protocol events, @@ -132,8 +136,10 @@ If the widget is realized, .B XtRemoveEventTypeHandler calls .B XSelectInput -if necessary. Specifying NULL for \fIselect_data\fP is equivalent to -specifying a pointer to an event mask containing 0. This is similar to the +if necessary. +Specifying NULL for \fIselect_data\fP is equivalent to +specifying a pointer to an event mask containing 0. +This is similar to the .B XtRemoveRawEventHandler function. .LP @@ -150,7 +156,8 @@ If \fImin_event_type\fP and \fImax_event_type\fP match the parameters to a previous call to .B XtRegisterExtensionSelector for the same display, the \fIproc\fP and \fIclient_data\fP replace the -previously registered values. If the range specified by \fImin_event_type\fP +previously registered values. +If the range specified by \fImin_event_type\fP and \fImax_event_type\fP overlaps the range of the parameters to a previous call for the same display in any other way, an error results. .LP @@ -159,7 +166,8 @@ The function registers the event dispatcher procedure specified by \fIproc\fP for events with the type \fIevent_type\fP. The previously registered dispatcher (or the default dispatcher if there was no previously registered -dispatcher) is returned. If \fIproc\fP is NULL, the default procedure is +dispatcher) is returned. +If \fIproc\fP is NULL, the default procedure is restored for the specified type. .LP In the future, when @@ -173,7 +181,8 @@ The function scans the list of registered event handlers for the specified widget and calls each handler that has been registered for the specified event type, subject to the \fIcontinue_to_dispatch\fP value returned by -each handler. The Intrinsics behave as if event handlers were registered +each handler. +The Intrinsics behave as if event handlers were registered at the head of the list for .BR Expose , .BR NoExpose , diff --git a/man/XtLastEventProcessed.man b/man/XtLastEventProcessed.man index c98b1d1..f74eb36 100644 --- a/man/XtLastEventProcessed.man +++ b/man/XtLastEventProcessed.man @@ -49,7 +49,8 @@ Specifies the open display connection. .B XtLastEventProcessed returns the last event passed to .B XtDispatchEvent -for the specified display and NULL if there has been no event. The +for the specified display and NULL if there has been no event. +The client must not modify the contents of the returned event. .LP .B XtLastTimestampProcessed diff --git a/man/XtOpenApplication.man b/man/XtOpenApplication.man index f449e4d..7c1a1ee 100644 --- a/man/XtOpenApplication.man +++ b/man/XtOpenApplication.man @@ -97,14 +97,17 @@ finally calls .B XtAppCreateShell with \fIapplication_name\fP NULL, the specified \fIwidget_class\fP, and the specified \fIargs\fP and \fInum_args\fP and returns the -created shell. The modified \fIargc\fP and \fIargv\fP returned by +created shell. +The modified \fIargc\fP and \fIargv\fP returned by .B XtDisplayInitialize are returned in \fIargc_in_out\fP and \fIargv_in_out\fP. If \fIapp_context_return\fP is not NULL, the created application context -is also returned. If the display specified by the command line cannot +is also returned. +If the display specified by the command line cannot be opened, an error message is issued and .B XtOpenApplication -terminates the application. If \fIfallback_resources\fP is non-NULL, +terminates the application. +If \fIfallback_resources\fP is non-NULL, .B XtAppSetFallbackResources is called with the value prior to calling .BR XtOpenDisplay . diff --git a/man/XtOwnSelection.man b/man/XtOwnSelection.man index b68b4cd..65d4b60 100644 --- a/man/XtOwnSelection.man +++ b/man/XtOwnSelection.man @@ -95,11 +95,13 @@ if the widget fails to obtain selection ownership in the first place. The .B XtOwnSelectionIncremental procedure informs the Intrinsics incremental selection mechanism that -the specified widget wishes to own the selection. It returns +the specified widget wishes to own the selection. +It returns .B True if the specified widget successfully becomes the selection owner or .B False -otherwise. For more information about \fIselection\fP, \fItarget\fP, +otherwise. +For more information about \fIselection\fP, \fItarget\fP, and \fItime\fP, see Section 2.6 of the \fIInter-Client Communication Conventions Manual\fP. .LP diff --git a/man/XtRegisterDrawable.man b/man/XtRegisterDrawable.man index f88bc18..352d0a3 100644 --- a/man/XtRegisterDrawable.man +++ b/man/XtRegisterDrawable.man @@ -55,7 +55,8 @@ Specifies the widget to register the drawable for. associates the specified drawable with the specified widget so that future calls to .B XtWindowToWidget -with the drawable will return the widget. The default event dispatcher +with the drawable will return the widget. +The default event dispatcher will dispatch future core events that arrive with the drawable to the widget as though the event contained the widget's window, but the event itself will not be changed in any way when being passed to even handler diff --git a/man/XtResolvePathname.man b/man/XtResolvePathname.man index 0c23ece..ad1c307 100644 --- a/man/XtResolvePathname.man +++ b/man/XtResolvePathname.man @@ -75,9 +75,11 @@ To set the language for all applications specify ``*xnlLanguage: \fIlang\fP'' in the resource database. The format and content of the language string are -implementation-defined. One suggested syntax is to compose +implementation-defined. +One suggested syntax is to compose the language string of three parts; a ``language part'', a -``territory part'' and a ``codeset part''. The manner in which +``territory part'' and a ``codeset part''. +The manner in which this composition is accomplished is implementation-defined and the \*(xI make no interpretation of the parts other than to use them in substitutions as described below. @@ -120,7 +122,8 @@ environment variable will be passed to If .B \s-1XFILESEARCHPATH\s+1 is not defined, an implementation-specific default path will be used -which contains at least 6 entries. These entries +which contains at least 6 entries. +These entries must contain the following substitutions: .nf @@ -141,7 +144,8 @@ with a colon, it will be preceded by %N%S. If the path includes two adjacent colons, \fB%N%S\fP will be inserted between them. .LP The \fItype\fP parameter is intended to be a category of files, usually -being translated into a directory in the pathname. Possible values +being translated into a directory in the pathname. +Possible values might include ``app-defaults'', ``help'', and ``bitmap''. .LP The \fIsuffix\fP parameter is intended to be appended to the file name. @@ -157,17 +161,20 @@ __projectroot__/lib/X11/%l/%T/%N%S:__projectroot__/lib/X11/%T/%N%S .LP Using this example, if the user has specified a language, it will be used as a subdirectory of __projectroot__/lib/X11 that will be searched -for other files. If the desired file is not found there, the lookup +for other files. +If the desired file is not found there, the lookup will be tried again using just the language part of the specification. If the file is not there, it will be looked for in -__projectroot__/lib/X11. The \fItype\fP parameter is used as a +__projectroot__/lib/X11. +The \fItype\fP parameter is used as a subdirectory of the language directory or of __projectroot__/lib/X11, and \fIsuffix\fP is appended to the file name. .LP The %D substitution allows the addition of path elements to the implementation-specific default path, typically to allow additional directories to be searched without preventing -resources in the system directories from being found. For example, a +resources in the system directories from being found. +For example, a user installing resource files under a directory called ``ourdir'' might set .B \s-1XFILESEARCHPATH\s+1 diff --git a/man/XtSetLanguageProc.man b/man/XtSetLanguageProc.man index 92de089..d82aecb 100644 --- a/man/XtSetLanguageProc.man +++ b/man/XtSetLanguageProc.man @@ -58,12 +58,15 @@ when it is called. sets the language procedure that will be called from .B XtDisplayInitialize for all subsequent Displays initialized in the specified application -context. If \fIapp_context\fP is NULL, the specified language procedure +context. +If \fIapp_context\fP is NULL, the specified language procedure is registered in all application contexts created by the calling process, -including any future application contexts that may be created. If +including any future application contexts that may be created. +If \fIproc\fP is NULL a default language procedure is registered. .B XtSetLanguageProc -returns the previously registered language procedure. If a language +returns the previously registered language procedure. +If a language procedure has not yet been registered, the return value is unspecified but if this return value is used in a subsequent call to .BR XtSetLanguageProc , @@ -71,16 +74,19 @@ it will cause the default language procedure to be registered. .LP The default language procedure does the following: .IP \(bu 5 -Sets the locale according to the environment. On ANSI C-based systems +Sets the locale according to the environment. +On ANSI C-based systems this is done by calling .BR setlocale ( .BR LC_ALL , -language ). If an error is encountered a warning message is issued with +language ). +If an error is encountered a warning message is issued with .BR XtWarning . .IP \(bu 5 Calls .B XSupportsLocale -to verify that the current locale is supported. If the locale is not +to verify that the current locale is supported. +If the locale is not supported, a warning message is issued with .B XtWarning and the locale is set to ``C''. @@ -89,7 +95,8 @@ Calls .B XSetLocaleModifiers specifying the empty string. .IP \(bu 5 -Returns the value of the current locale. On ANSI C-based systems this +Returns the value of the current locale. +On ANSI C-based systems this is the return value from a final call to .BR setlocale ( .BR LC_ALL , diff --git a/man/XtSetSelectionParameters.man b/man/XtSetSelectionParameters.man index 082fe65..6a2365a 100644 --- a/man/XtSetSelectionParameters.man +++ b/man/XtSetSelectionParameters.man @@ -44,7 +44,8 @@ Atom \fItype\fP, XtPointer \fIvalue\fP, unsigned long \fIlength\fP, int \fIformat\fP); .SH ARGUMENTS .IP \fIrequestor\fP 1i -Specifies the widget making the request. Must be of class Core or any +Specifies the widget making the request. +Must be of class Core or any subclass thereof. .IP \fIselection\fP 1i Specifies the atom that names the selection. @@ -59,20 +60,23 @@ element of a sized indicated by \fIformat\fP. Specifies the size in bits of the data in the elements of \fIvalue\fP. .SH DESCRIPTION The specified parameters will be copied and stored in a new property of -the specified type and format on the requestor's window. To initiate a +the specified type and format on the requestor's window. +To initiate a selection request with a target and these parameters, a subsequent call to .B XtGetSelectionValue or to .B XtGetSelectionValueIncremental specifying the same requestor widget and selection atom will generate a .B ConvertSelection -request referring referring to the property containing the parameters. If +request referring referring to the property containing the parameters. +If .B XtSetSelectionParameters is called more than once with the same widget and selection without a call to specify a request, the most recently specified parameters are used in the subsequent request. .LP -The possible values of \fIformat\fP may be 8, 16, or 32. If the \fIformat\fP +The possible values of \fIformat\fP may be 8, 16, or 32. +If the \fIformat\fP is 8, the elements of \fIvalue\fP are assumed to be sizeof(char); if 16, sizeof(short); if 32, sizeof(long). .LP diff --git a/man/XtSetWMColormapWindows.man b/man/XtSetWMColormapWindows.man index 0137ab7..9231cfb 100644 --- a/man/XtSetWMColormapWindows.man +++ b/man/XtSetWMColormapWindows.man @@ -44,7 +44,8 @@ void XtSetWMColormapWindows(Widget \fIwidget\fP, Widget* \fIlist\fP, Cardinal .SH ARGUMENTS .IP \fIwidget\fP 1i Specifies the widget on whose window the WM_COLORMAP_WINDOWS property -will be stored. Must be of class Core or any subclass thereof. +will be stored. +Must be of class Core or any subclass thereof. .IP \fIlist\fP 1i Specifies a list of widgets whose windows are are potentially to be listed in the WM_COLORMAP_WINDOWS property. @@ -53,7 +54,8 @@ Specifies the number of widgets in \fIlist\fP. .SH DESCRIPTION .B XtSetWMColormapWindows returns immediately if \fIwidget\fP is not realized or if \fIcount\fP -is zero. Otherwise, +is zero. +Otherwise, .B XtSetWMColormapWindows constructs an ordered list of windows by examining each widget in \fIlist\fP in turn and ignoring the widget if it is not realized, diff --git a/man/XtToolkitThreadInitialize.man b/man/XtToolkitThreadInitialize.man index e124be5..4eea194 100644 --- a/man/XtToolkitThreadInitialize.man +++ b/man/XtToolkitThreadInitialize.man @@ -43,7 +43,8 @@ Boolean XtToolkitThreadInitialize(void); .SH DESCRIPTION If .B XtToolkitThreadInitialize -was previously called, it returns. The application programmer must ensure +was previously called, it returns. +The application programmer must ensure that two or more threads do not simultaneously attempt to call .BR XtToolkitThreadInitialize ; the effect of this is undefined. diff --git a/man/XtVaCreateArgsList.man b/man/XtVaCreateArgsList.man index 43cd210..3c0a2d4 100644 --- a/man/XtVaCreateArgsList.man +++ b/man/XtVaCreateArgsList.man @@ -55,10 +55,12 @@ pointer, which may be used with The end of both lists is identified by a \fIname\fP entry containing NULL. Any entries of type .B XtVaTypedArg -are copied as specified without applying conversions. Data passed by +are copied as specified without applying conversions. +Data passed by reference (including Strings) are not copied, only the pointers themselves; the caller must ensure that the data remain valid for -the lifetime of the created varargs list. The list should be freed +the lifetime of the created varargs list. +The list should be freed using .B XtFree when no longer needed. |