Партнёры:
Хостинг:
NAME
DtToolTip(3) - the tooltip application interface.
SYNOPSIS
#include <Dt/Tooltip.h>
DESCRIPTION
This man page describes the desktop tooltip application
interface that can be used by developers to utilize the the
tooltip functionality. This functionality is split into two
areas, the display interface and the manager interface.
The display interface is responsible for the display of a
tooltip window containing a specified text label, which also
includes time delays associated with the display (pop up)
and removal (pop down) of the tooltip window.
The manager interface uses the display interface to manage
the tooltip functionality of primitive widgets and gadgets.
Consequently, the manager interface instigates the display
and removal of a tooltip window when the pointer enters and
leaves a primitive widget or gadget. The manager interface
also associates tooltip status with primitive widgets and
gadgets via X resources. Such tooltip status includes the
tooltip label and a boolean flag indicating whether or not a
tooltip should be displayed.
The majority of developers will make use of the manager
interface to efficiently add tooltips to buttons on toolbars
and to manage the display of the tooltip window. The manager
interface may be used to efficiently add tooltips to buttons
on toolbars and to manage the display of the tooltip window.
Since the manager interface is linked with the X resource
mechanism tooltip labels may be defined in resource files.
All that is required is one procedure call per widget
requiring tooltip functionality and the addition of one
include file.
A general overview of each interface is described in terms
of the features that may be used. This description will
involve references to procedures and X resources of the
interfaces. These associated name spaces are then described
in more detail in the appropriate sections.
The Display Interface
The Display interface is responsible for the display of a
tooltip window containing a specified text label, which also
includes time delays associated with the display (pop up)
and removal (pop down) of the tooltip window.
Additionally the application shell is created with the same
application name and application class as the top level
widget passed to the create procedure. This ensures that the
tooltip display resources may be application specific.
Class Description
The DtTooltipDisplay widget inherits behavior and resources
from Core, Composite, Shell, and OverrideShell classes.
The class pointer is dtTooltipDisplayWidgetClass.
The class name is DtTooltipDisplay.
Functions
#include <Dt/Tooltip.h>
Widget DtCreateTooltipDisplay (Widget parent, char* name,
ArgList arglist, Cardinal argcount)
Creates an instance of a Tooltip display widget and
returns the associated widget ID.
parent
Specifies the parent widget ID.
name Specifies the name of the created widget.
arglist
Specifies the argument list.
argcount
Specifies the number of attribute.value pairs in the
argument list (arglist).
void DtTooltipDisplayPopup (Widget tooltipdisplay)
Displays the tooltip window using the previously speci-
fied tooltip label and position. The tooltip label may
be modified between invocations using the XmNlabel-
String resource.
tooltipdisplay
Specifies the Tooltip display widget.
void DtTooltipDisplayPopupAtLocation (Widget tooltipdisplay,
XRectangle* rectangle, String tooltiplabel)
Displays the tooltip window using a constraint rectan-
gle to display the tooltip next to and a text label.
tooltipdisplay
Specifies the Tooltip display widget.
rectangle
Specifies the constraint rectangle next to which the
tooltip window will be displayed.
tooltiplabel
Specifies the tooltip label that will be displayed
inside the tooltip window.
void DtTooltipDisplayPopdown (Widget tooltipdisplay)
Pops down the displayed tooltip window.
tooltipdisplay
Specifies the Tooltip display widget.
Resources
DtToolTip Display Resource Set
Name Class Type Default Access
__________________________________________________________________________________________________________
DtNpopdownDelay DtCPopdownDelay Cardinal 0 CSG
DtNpopupFirstDelay DtCPopupFirstDelay Cardinal 1000 CSG
DtNpopupTransitionDelay DtCPopupTransitionDelay Cardinal 100 CSG
DtNpopupTransitionInterval DtCPopupTransitionInterval Cardinal 2000 CSG
DtNtooltipBackground DtCTooltipBackground Pixel LightGoldenRodYellow CSG
DtNtooltipForeground DtCTooltipForeground Pixel Black CSG
DtNtooltipPopNotifyCallback DtCTooltipPopNotifyCallback XtCallbackList NULL CSG
DtNtooltipStatusSensitive DtCTooltipStatusSensitive Boolean True CSG
DtNwindowOffset DtCWindowOffset Dimension 4 CSG
XmNalignment XmCAlignment unsigned char XmALIGNMENT_BEGINING CSG
XmNattachment XmCAttachment unsigned char XmATTACH_SOUTH CSG
XmNfontSet XmCFontSet FontSet Dynamic CSG
XmNlabelString XmCLabelString String NULL CSG
XmNmarginHeight XmCMarginHeight Dimension 2 CSG
XmNmarginWidth XmCMarginWidth Dimension 2 CSG
XmNsensitive XmCSensitive Boolean True CSG
DtNpopdownDelay
Specifies a time delay representing the interval of
time that the tooltip will remain popped up after which
the tooltip will automatically pop down. Units are
specified in milli seconds. A value of 0 states no pop
down delay so the tooltip window will stay present
until popped down by other means.
DtNpopupFirstDelay
Specifies the time delay representing the interval of
time that will occur between a pop up request and
actual display of the tooltip window. Units are speci-
fied in milli seconds.
DtNpopupTransitionDelay
Specifies an additional time delay representing the
interval of time that will occur between a pop up
request and actual display of the tooltip window. Units
are specified in milli seconds.
DtNpopupTransitionInterval
Specifies the interval of time that will be used to
decide which time delay to use for pop up, either
DtNpopupFirstDelay or DtNpopupTransitionDelay. If the
time interval between a previous display of the tooltip
window and a request for pop up is greater than DtNpo-
pupTransitionInterval then DtNpopupFirstDelay is used
as the pop up delay, otherwise DtNpopupTransitionDelay
is used. Units are specified in milli seconds.
DtNtooltipBackground
Specifies the colour of the tooltip window.
DtNtooltipForeground
Specifies the colour of the tooltip text.
DtNtooltipPopNotifyCallback
Specifies the call back list of procedures to be called
when the tooltip item popped up and down. Specifically
the callbacks are called immediately before the display
and immediately after removal of the tooltip window. If
a tooltip item is associated with the display of the
tooltip and it has a non default DtNtooltipPopNotify-
Callback resource value then the callback list for the
display widget is not called.
DtNtooltipStatusSensitive
Specifies if tooltip status label display is sensitive.
This resource may be applied to switch off all status
label display for tooltips.
DtNwindowOffset
Specifies the offset, in pixels, between the given con-
straint rectangle and the tooltip window.
XmNalignment
Specifies the alignment of the tooltip window on a
chosen edge. Valid resource values are:
XmALIGNMENT_BEGINNING
Align the left hand side of the tooltip window at the
beginning of the edge.
XmALIGNMENT_CENTER
Align the centre of the tooltip window at the center of
the edge.
XmALIGNMENT_END
Align the right hand side of the tooltip window at the
end of the edge.
If the chosen alignment results in clipping of the
tooltip widow with the screen then the tooltip window
is aligned to the closest screen edge.
XmNattachment
Specifies the edge attachment of the tooltip window
corresponding to the edges defined by the constraint
rectangle. Valid resource values are:
XmATTACH_NORTH
Attach the tooltip to the northern edge.
XmATTACH_EAST
Attach the tooltip to the eastern edge.
XmATTACH_SOUTH
Attach the tooltip to the southern edge.
XmATTACH_WEST
Attach the tooltip to the eastern edge.
If the chosen edge attachment results in clipping of
the tooltip window with the screen then the opposite
edge is chosen.
XmNfontSet
Specifies the font to use for display of the text
inside the tooltip window.
XmNlabelString
Specifies the tooltip text to be displayed inside the
tooltip label.
XmNmarginHeight
Specifies the margin height between the tooltip text
and the tooltip window.
XmNmarginWidth
Specifies the margin width between the tooltip text and
the tooltip window.
XmNsensitive
Specifies if the tooltip display will respond to pop up
requests. If false then the tooltip window will not be
displayed when requested. This resource may be applied
to switch all tooltips on or off.
Inherited Resources
Shell Resource Set
Name Class Type Default Access
____________________________________________________________________________________________________
XmNallowShellResize XmCAllowShellResize Boolean True G
XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG
XmNgeometry XmCGeometry String NULL CSG
XmNoverrideRedirect XmCOverrideRedirect Boolean True CSG
XmNpopdownCallback XmCCallback XtCallbackList NULL C
XmNpopupCallback XmCCallback XtCallbackList NULL C
XmNsaveUnder XmCSaveUnder Boolean True CSG
XmNvisual XmCVisual Visual * CopyFromParent CSG
Composite Resource Set
Name Class Type Default Access
______________________________________________________________________
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG
XmNnumChildren XmCReadOnly Cardinal 0 G
Core Resource Set
Name Class Type Default Access
_______________________________________________________________________________________________________________
XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG
XmNancestorSensitive XmCSensitive Boolean dynamic G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 1 CSG
XmNcolormap XmCColormap Colormap dynamic CG
XmNdepth XmCDepth int dynamic CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension dynamic CSG
XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Screen * dynamic
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations dynamic CSG
XmNwidth XmCWidth Dimension dynamic CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Callback Information
The value of either True or False is passed to the callback
of a DtNtooltipPopNotifyCallback procedure, corresponding to
whether the tooltip display window is about to display or
has been removed.
The Manager Interface
The manager interface enables the developer to efficiently
add tooltip functionality to primitive widgets and gadgets
without the need to manage tooltip display and state of the
tooltip enabled items. The manager interface utilises the
tooltip display interface and will automatically create an
instance of the tooltip display widget, which is subse-
quently used by all tooltip items created using the manager
interface.
The Manager interface uses the display interface to manage
tooltip functionality for primitive widgets and gadgets.
Thus the manager interface instigates display and removal of
a tooltip window when the pointer enters and leaves a primi-
tive widget or gadget and associates tooltip status with
primitive widgets and gadgets via X resources. Such tooltip
status includes the tooltip label and a boolean flag indi-
cating whether or not a tooltip should be displayed.
References to tooltip items are maintained via the primitive
widget or gadget IDs. There is no requirement for the
developer to maintain additional information. The tooltip
display widget is used to efficiently maintain cross
references between the primitive widget or gadget and the
tooltip item.
When the procedure DtTooltipItemCreate is first called for a
widget on a particular screen it will create an instance of
a Tooltip display widget on the appropriate screen. First a
new application shell is created on the same screen as the
widget in question then the DtTooltipDisplay widget is
created with the new application shell as its parent. This
ensures the tooltip display widget will not be deleted if
any top level widgets of the main application are deleted.
A tooltip item is created for a primitive widget or gadget
by using the procedure DtCreateTooltipItem. This call will
ensure that when the pointer enters the area of the primi-
tive widget or gadget a request for pop up of the tooltip
window occurs. When the pointer leaves the area or a
key/button press occurs the tooltip window is popped down.
It ensures that the tooltip state information is passed to
the tooltip display via a tooltip item context reference.
Hence when a tooltip item enabled primitive widget or gadget
needs to display the tooltip window the manager ensures than
the tooltip item context reference is switched to the
corresponding primitive widget or gadget tooltip item.
To enable tooltip display and removal of the tooltip window
it is necessary to add event handlers to primitive widgets
manager widget and gadgets. Addition is dependent on whether
the item being created is associated with a primitive widget
or a gadget. If the tooltip item is attached to a primitive
widget then an event handler is added with the following
event masks: EnterWindowMask, LeaveWindowMask, But-
tonPressMask, KeyPressMask. If the tooltip item is attached
to a gadget the the following events masks are added to its
parent: EnterWindowMask, LeaveWindowMask, ButtonPressMask,
KeyPressMask, PointerMotionMask.
Functions
#include <Dt/Tooltip.h>
void DtCreateTooltipItem (Widget widget, ArgList arglist,
Cardinal argcount)
Creates a tooltip item to be associated with a widget
so that when the pointer enters the widget a tooltip
window will be displayed containing a tooltip label.
This label is either passed as the resource DtNtoolti-
pLabel or is contained in the X resource database and
linked to the associated widget.
widget
The widget, either a primitive widget or gadget, that
will be tooltip enabled.
arglist
Specifies the argument list
argcount
Specifies the number of attribute.value pairs in the
argument list (arglist)
void DtDestroyTooltipItem (Widget widget)
Destroys a tooltip item associate with a widget. This
is also occurs if the tooltip enabled widget is des-
troyed.
widget
The widget, either a primitive widget or gadget, that
has tooltip enabled functionality.
void DtTooltipItemSetValues (Widget widget, ArgList arglist,
Cardinal argcount)
Set tooltip resources for a tooltip enabled widget.
widget
The widget, either a primitive widget or gadget, that
has tooltip enabled functionality.
arglist
Specifies the argument list
argcount
Specifies the number of attribute.value pairs in the
argument list (arglist)
If the resource DtNtooltipLabel is modified while the
tooltip window is displayed for the item widget the
tooltip window is automatically adjusted to display the
new text label.
void DtTooltipItemGetValues (Widget widget, ArgList arglist,
Cardinal argcount)
Get tooltip resource for a tooltip enabled widget.
widget
The widget, either a primitive widget or gadget, that
has tooltip enabled functionality.
arglist
Specifies the argument list.
argcount
Specifies the number of attribute.value pairs in the
argument list (arglist).
Widget DtTooltipItemGetTooltipDisplay (Widget widget)
Returns the tooltip display widget associated with a
specific widget.
widget
The widget, either a primitive widget or gadget, that
has tooltip enabled functionality.
If no tooltip item exists for the widget then a NULL is
returned.
Resources
Tooltip Item Resource Set
Name Class Default Type Access
__________________________________________________________________________________________
DtNtooltipLabel DtCTooltipLabel String NULL CSG
DtNtooltipPopNotifyCallback DtCTooltipPopNotifyCallback XtCallbackList NULL CSG
DtNtooltipSensitive DtCTooltipSensitive Boolean True CSG
DtNtooltipStatusLabel DtCTooltipStatusLabel String NULL CSG
DtNtooltipStatusWidget DtCTooltipStatusWidget Widget NULL CSG
DtNtooltipLabel
Specifies the tooltip label to use for the associated
item.
DtNtooltipPopNotifyCallback
Specifies the call back list of procedures to be called
when the tooltip item popped up and down. Specifically
the callbacks are called immediately before the display
and immediately after removal of the tooltip window.
DtNtooltipSensitive
Specifies if the tooltip label is sensitive. If false
the tooltip label will not be displayed.
DtNtooltipStatusLabel
Specifies the tooltip status label to be used for the
associated item. This resource is used in conjuction
with the DtNtooltipStatusWidget resource.
If the resource value is NULL then no status label is
displayed.
DtNtooltipStatusWidget
Specifies the tooltip status widget that is used to
display the status label defined by the DtNtooltipSta-
tusLabel resource. It is assumed that the specified
widget uses the resource XmNlabelString. Conversion
from type String to XmString is automatically performed
by the API. No assumption is made about where the
status widget resides.
If the resource value is NULL then no status label is
displayed, hence this resource may be used to individu-
ally switch on or off status label display for tooltip
items.
Callback Information
The value of either True or False is passed to the callback
of a DtNtooltipPopNotifyCallback procedure, corresponding to
whether the tooltip display window is about to display or
has been removed.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |