


XmPrimitive(3X)						      XmPrimitive(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmPPrriimmiittiivvee -	The Primitive widget class

SYNOPSIS


  ##iinncclluuddee <<XXmm//XXmm..hh>>

DESCRIPTION
  Primitive is a widget	class used as a	supporting superclass for other
  widget classes.  It handles border drawing and highlighting, traversal
  activation and deactivation, and various callback lists needed by Primitive
  widgets.

  Classes

  Primitive inherits behavior and resources from CCoorree class.

  The class pointer is xxmmPPrriimmiittiivveeWWiiddggeettCCllaassss.

  The class name is XXmmPPrriimmiittiivvee.

  New Resources

  The following	table defines a	set of widget resources	used by	the program-
  mer to specify data.	The programmer can also	set the	resource values	for
  the inherited	classes	to set attributes for this widget.  To reference a
  resource by name or by class in a .Xdefaults file, remove the	XXmmNN or XXmmCC
  prefix and use the remaining letters.	 To specify one	of the defined values
  for a	resource in a .Xdefaults file, remove the XXmm prefix and	use the
  remaining letters (in	either lowercase or uppercase, but include any under-
  scores between words).  The codes in the access column indicate if the
  given	resource can be	set at creation	time (C), set by using XXttSSeettVVaalluueess
  (S), retrieved by using XXttGGeettVVaalluueess (G), or is not applicable	(N/A).

			   XXmmPPrriimmiittiivvee RReessoouurrccee	SSeett
	______________________________________________________________
	NNaammee			      DDeeffaauulltt			AAcccceessss
	      CCllaassss			    TTyyppee
	______________________________________________________________
	______________________________________________________________
	XmNbottomShadowColor	      dynamic			CSG
	      XmCBottomShadowColor	     Pixel
	______________________________________________________________
	XmNbottomShadowPixmap	      XmUNSPECIFIED_PIXMAP	CSG
	      XmCBottomShadowPixmap	     Pixmap
	______________________________________________________________
	XmNforeground		      dynamic			CSG
	      XmCForeground		     Pixel
	______________________________________________________________
	XmNhelpCallback		      NULL			C
	      XmCCallback		     XtCallbackList
	______________________________________________________________
	XmNhighlightColor	      dynamic			CSG
	      XmCHighlightColor		     Pixel
	______________________________________________________________
	XmNhighlightOnEnter	      False			CSG
	      XmCHighlightOnEnter	     Boolean
	______________________________________________________________
	XmNhighlightPixmap	      dynamic			CSG
	      XmCHighlightPixmap	     Pixmap
	______________________________________________________________
	XmNhighlightThickness	      2				CSG
	      XmCHighlightThickness	     Dimension
	______________________________________________________________
	XmNnavigationType	      XmNONE			CSG
	      XmCNavigationType		     XmNavigationType
	______________________________________________________________
	XmNshadowThickness	      2				CSG
	      XmCShadowThickness	     Dimension
	______________________________________________________________
	XmNtopShadowColor	      dynamic			CSG
	      XmCTopShadowColor		     Pixel
	______________________________________________________________
	XmNtopShadowPixmap	      dynamic			CSG
	      XmCTopShadowPixmap	     Pixmap
	______________________________________________________________
	XmNtraversalOn		      True			CSG
	      XmCTraversalOn		     Boolean
	______________________________________________________________
	XmNunitType		      dynamic			CSG
	      XmCUnitType		     unsigned char
	______________________________________________________________
	XmNuserData		      NULL			CSG
	      XmCUserData		     XtPointer
	______________________________________________________________

  XXmmNNbboottttoommSShhaaddoowwCCoolloorr
	    Specifies the color	to use to draw the bottom and right sides of
	    the	border shadow.	This color is used if the XXmmNNttooppSShhaaddoowwPPiixxmmaapp
	    resource is	unspecified.

  XXmmNNbboottttoommSShhaaddoowwPPiixxmmaapp
	    Specifies the pixmap to use	to draw	the bottom and right sides of
	    the	border shadow.

  XXmmNNffoorreeggrroouunndd
	    Specifies the foreground drawing color used	by Primitive widgets.

  XXmmNNhheellppCCaallllbbaacckk
	    Specifies the list of callbacks that is called when	the help key
	    is pressed.	 The reason sent by the	callback is XXmmCCRR__HHEELLPP.

  XXmmNNhhiigghhlliigghhttCCoolloorr
	    Specifies the color	of the highlighting rectangle.	This color is
	    used if the	highlight pixmap resource is XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP.

  XXmmNNhhiigghhlliigghhttOOnnEEnntteerr
	    Specifies if the highlighting rectangle is drawn when the cursor
	    moves into the widget.  If the shell's focus policy	is XXmmEEXXPPLLII--
	    CCIITT, this resource is ignored, and the widget is highlighted when
	    it has the focus.  If the shell's focus policy is XXmmPPOOIINNTTEERR	and
	    if this resource is	True, the highlighting rectangle is drawn
	    when the the cursor	moves into the widget.	If the shell's focus
	    policy is XXmmPPOOIINNTTEERR	and if this resource is	False, the highlight-
	    ing	rectangle is not drawn when the	the cursor moves into the
	    widget.  The default is False.

  XXmmNNhhiigghhlliigghhttPPiixxmmaapp
	    Specifies the pixmap used to draw the highlighting rectangle.

  XXmmNNhhiigghhlliigghhttTThhiicckknneessss
	    Specifies the thickness of the highlighting	rectangle.

  XXmmNNnnaavviiggaattiioonnTTyyppee
	    Determines whether the widget is a tab group.

	      oo++
	      XXmmNNOONNEE indicates that the	widget is not a	tab group.

	      oo++
	      XXmmTTAABB__GGRROOUUPP indicates that the widget is a tab group, unless
	      another widget in	the hierarchy has an XXmmNNnnaavviiggaattiioonnTTyyppee of
	      XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP.

	      oo++
	      XXmmSSTTIICCKKYY__TTAABB__GGRROOUUPP indicates that	the widget is a	tab group,
	      even if another widget in	the hierarchy has an XXmmNNnnaavviiggaattiioonn--
	      TTyyppee of XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP.

	      oo++
	      XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP indicates that the widget is a tab group
	      and that widgets in the hierarchy	whose XXmmNNnnaavviiggaattiioonnTTyyppee	is
	      XXmmTTAABB__GGRROOUUPP are not tab groups.

	      When a parent widget has an XXmmNNnnaavviiggaattiioonnTTyyppee of
	      XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP, traversal of non-tab-group	widgets
	      within the group is based	on the order of	those widgets in
	      their parent's XXmmNNcchhiillddrreenn list.

	      When any widget in a hierarchy has an XXmmNNnnaavviiggaattiioonnTTyyppee of
	      XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP, traversal of tab groups in	the hierarchy
	      proceeds to widgets in the order in which	their XXmmNNnnaavviiggaattiioonn--
	      TTyyppee resources were specified as XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP or
	      XXmmSSTTIICCKKYY__TTAABB__GGRROOUUPP, whether by creating the widgets with that
	      value, by	calling	XXttSSeettVVaalluueess, or	by calling XXmmAAddddTTaabbGGrroouupp.

  XXmmNNsshhaaddoowwTThhiicckknneessss
	    Specifies the size of the drawn border shadow.

  XXmmNNttooppSShhaaddoowwCCoolloorr
	    Specifies the color	to use to draw the top and left	sides of the
	    border shadow.  This color is used if the XXmmNNttooppSShhaaddoowwPPiixxmmaapp
	    resource is	unspecified.

  XXmmNNttooppSShhaaddoowwPPiixxmmaapp
	    Specifies the pixmap to use	to draw	the top	and left sides of the
	    border shadow.

  XXmmNNttrraavveerrssaallOOnn
	    Specifies if traversal is activated	for this widget.  In Cascade-
	    Button and CascadeButtonGadget, this resource is forced to TRUE
	    unless the parent is an OptionMenu.

  XXmmNNuunniittTTyyppee
	    Provides the basic support for resolution independence.  It
	    defines the	type of	units a	widget uses with sizing	and position-
	    ing	resources.  If the widget's parent is a	subclass of XXmmMMaannaaggeerr
	    and	if the XXmmNNuunniittTTyyppee resource is not explicitly set, it
	    defaults to	the unit type of the parent widget.  If	the widget's
	    parent is not a subclass of	XXmmMMaannaaggeerr, the resource	has a default
	    unit type of XXmmPPIIXXEELLSS.

	    XXmmNNuunniittTTyyppee	can have the following values:

	      oo++
	      XXmmPPIIXXEELLSS-all values provided to the widget are treated as	nor-
	      mal pixel	values.

	      oo++
	      XXmm110000TTHH__MMIILLLLIIMMEETTEERRSS-all values provided to the widget are
	      treated as 1/100 millimeter.

	      oo++
	      XXmm11000000TTHH__IINNCCHHEESS-all values provided to the widget	are treated
	      as 1/1000	inch.

	      oo++
	      XXmm110000TTHH__PPOOIINNTTSS-all values	provided to the	widget are treated as
	      1/100 point.  A point is a unit used in text processing appli-
	      cations and is defined as	1/72 inch.

	      oo++
	      XXmm110000TTHH__FFOONNTT__UUNNIITTSS-all values provided to	the widget are
	      treated as 1/100 of a font unit.	A font unit has	horizontal
	      and vertical components.	These are the values of	the XmScreen
	      resources	XXmmNNhhoorriizzoonnttaallFFoonnttUUnniitt and XXmmNNvveerrttiiccaallFFoonnttUUnniitt.

  XXmmNNuusseerrDDaattaa
	    Allows the application to attach any necessary specific data to
	    the	widget.	 It is an internally unused resource.

  Dynamic Color	Defaults

  The foreground, background, top shadow, bottom shadow, and highlight color
  resources are	dynamically defaulted.	If no color data is specified, the
  colors are automatically generated.  On a single-plane system, a black and
  white	color scheme is	generated.  Otherwise, four colors are generated,
  which	display	the correct shading for	the 3-D	visuals.  If the background
  is the only color specified for a widget, the	top shadow and bottom shadow
  colors are generated to give the 3-D appearance.  Foreground and highlight
  colors are generated to provide sufficient contrast with the background
  color.

  Colors are generated only at creation.  Resetting the	background through
  XXttSSeettVVaalluueess does not regenerate the other colors.  XXmmCChhaannggeeCCoolloorr can be
  used to recalculate all associated colors based on a new background color.

  Inherited Resources

  Primitive inherits behavior and resources from the following superclass.
  For a	complete description of	each resource, refer to	the man	page for that
  superclass.

			      CCoorree RReessoouurrccee SSeett
     ____________________________________________________________________
     NNaammee				   DDeeffaauulltt		   AAcccceessss
	   CCllaassss				 TTyyppee
     ____________________________________________________________________
     ____________________________________________________________________
     XmNaccelerators			   dynamic		   CSG
	   XmCAccelerators			  XtAccelerators
     ____________________________________________________________________
     XmNancestorSensitive		   dynamic		   G
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNbackground			   dynamic		   CSG
	   XmCBackground			  Pixel
     ____________________________________________________________________
     XmNbackgroundPixmap		   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderColor			   XtDefaultForeground	   CSG
	   XmCBorderColor			  Pixel
     ____________________________________________________________________
     XmNborderPixmap			   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderWidth			   0			   CSG
	   XmCBorderWidth			  Dimension
     ____________________________________________________________________
     XmNcolormap			   dynamic		   CG
	   XmCColormap				  Colormap
     ____________________________________________________________________
     XmNdepth				   dynamic		   CG
	   XmCDepth				  int
     ____________________________________________________________________
     XmNdestroyCallback			   NULL			   C
	   XmCCallback				  XtCallbackList
     ____________________________________________________________________
     XmNheight				   dynamic		   CSG
	   XmCHeight				  Dimension
     ____________________________________________________________________
     XmNinitialResourcesPersistent	   True			   C
	   XmCInitialResourcesPersistent	  Boolean
     ____________________________________________________________________
     XmNmappedWhenManaged		   True			   CSG
	   XmCMappedWhenManaged			  Boolean
     ____________________________________________________________________
     XmNscreen				   dynamic		   CG
	   XmCScreen				  Screen *
     ____________________________________________________________________
     XmNsensitive			   True			   CSG
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNtranslations			   dynamic		   CSG
	   XmCTranslations			  XtTranslations
     ____________________________________________________________________
     XmNwidth				   dynamic		   CSG
	   XmCWidth				  Dimension
     ____________________________________________________________________
     XmNx				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________
     XmNy				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________

  Callback Information

  A pointer to the following structure is passed to each callback:


  ttyyppeeddeeff ssttrruucctt
  {{
    iinntt		 _r_e_a_s_o_n;;
    XXEEvveenntt	 * _e_v_e_n_t;;
  }} XXmmAAnnyyCCaallllbbaacckkSSttrruucctt;;

  _r_e_a_s_o_n Indicates why the callback was	invoked.  For this callback, _r_e_a_s_o_n
	 is set	to XXmmCCRR__HHEELLPP.

  _e_v_e_n_t	 Points	to the XXEEvveenntt that triggered the callback.



  Translations

  The XmPrimitive translations are listed below.  These	translations may not
  directly correspond to a translation table.


  Note that for	buttons	in menus, altering translations	in ##oovveerrrriiddee or	##aauugg--
  mmeenntt mode is undefined.

       KKUUpp::	      PPrriimmiittiivveeTTrraavveerrsseeUUpp(())
       KKDDoowwnn::	      PPrriimmiittiivveeTTrraavveerrsseeDDoowwnn(())
       KKLLeefftt::	      PPrriimmiittiivveeTTrraavveerrsseeLLeefftt(())
       KKRRiigghhtt::	      PPrriimmiittiivveeTTrraavveerrsseeRRiigghhtt(())
       KKBBeeggiinnLLiinnee::    PPrriimmiittiivveeTTrraavveerrsseeHHoommee(())
       KKNNeexxttFFiieelldd::    PPrriimmiittiivveeNNeexxttTTaabbGGrroouupp(())
       KKPPrreevvFFiieelldd::    PPrriimmiittiivveePPrreevvTTaabbGGrroouupp(())
       KKAAccttiivvaattee::     PPrriimmiittiivveePPaarreennttAAccttiivvaattee(())
       KKCCaanncceell::	      PPrriimmiittiivveePPaarreennttCCaanncceell(())
       KKHHeellpp::	      PPrriimmiittiivveeHHeellpp(())

  Action Routines

  The XmPrimitive action routines are described	below:

  PPrriimmiittiivveeHHeellpp(()):
	    Calls the callbacks	for XXmmNNhheellppCCaallllbbaacckk if any exist.  If there
	    are	no help	callbacks for this widget, this	action calls the help
	    callbacks for the nearest ancestor that has	them.

  PPrriimmiittiivveeNNeexxttTTaabbGGrroouupp(()):
	    Traverses to the first item	in the next tab	group.	If the
	    current tab	group is the last entry	in the tab group list, it
	    wraps to the beginning of the tab group list.

  PPrriimmiittiivveePPaarreennttAAccttiivvaattee(()):
	    If the parent is a manager,	passes the KKAAccttiivvaattee event received
	    by the widget to the parent.

  PPrriimmiittiivveePPaarreennttCCaanncceell(()):
	    If the parent is a manager,	Passes the KKCCaanncceell event received by
	    the	widget to the parent.

  PPrriimmiittiivveePPrreevvTTaabbGGrroouupp(()):
	    Traverses to the first item	in the previous	tab group.  If the
	    beginning of the tab group list is reached,	it wraps to the	end
	    of the tab group list.

  PPrriimmiittiivveeTTrraavveerrsseeDDoowwnn(()):
	    Traverses to the next item below the current widget	in the
	    current tab	group, wrapping	if necessary.

  PPrriimmiittiivveeTTrraavveerrsseeHHoommee(()):
	    Traverses to the first widget or gadget in the current tab group.

  PPrriimmiittiivveeTTrraavveerrsseeLLeefftt(()):
	    Traverses to the next item to the left of the current widget in
	    the	current	tab group, wrapping if necessary.

  PPrriimmiittiivveeTTrraavveerrsseeNNeexxtt(()):
	    Traverses to the next item in the current tab group, wrapping if
	    necessary.

  PPrriimmiittiivveeTTrraavveerrsseePPrreevv(()):
	    Traverses to the previous item in the current tab group, wrapping
	    if necessary.


  PPrriimmiittiivveeTTrraavveerrsseeRRiigghhtt(()):
	    Traverses to the next item to the right of the current gadget in
	    the	current	tab group, wrapping if necessary.



  PPrriimmiittiivveeTTrraavveerrsseeUUpp(()):
	    Traverses to the next item above the current gadget	in the
	    current tab	group, wrapping	if necessary.

  Additional Behavior

  This widget has the additional behavior described below:

  <<FFooccuussIInn>>:
	    If the shell's keyboard focus policy is XXmmEEXXPPLLIICCIITT,	highlights
	    the	widget and gives it the	focus.

  <<FFooccuussOOuutt>>:
	    If the shell's keyboard focus policy is XXmmEEXXPPLLIICCIITT,	unhighlights
	    the	widget and removes the focus.

  Virtual Bindings

  The bindings for virtual keys	are vendor specific.  For information about
  bindings for virtual buttons and keys, see VViirrttuuaallBBiinnddiinnggss((33XX)).

RELATED	INFORMATION
  CCoorree((33XX)), XXmmCChhaannggeeCCoolloorr((33XX)), and XXmmSSccrreeeenn((33XX)).










































