XtGetApplicationResources man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

XtGetApplicationResources()			   XtGetApplicationResources()

Name
  XtGetApplicationResources - set application variables from the resource
  database.

Synopsis
  void XtGetApplicationResources(object, base, resources,  num_resources,
  args, num_args)
	 Widget object;
	 XtPointer base;
	 XtResourceList resources;
	 Cardinal num_resources;
	 ArgList args;
	 Cardinal num_args;

Inputs
  object    Specifies the object that identifies the resource database to
	    search; may be of class Object or any subclass.

  base	    Specifies the base address of the structure	 into  which  the
	    resource values will be written.

  resources Specifies the application's resource list.

  num_resources
	    Specifies the number of resources in the resource list.

  args	    Specifies the argument list to override other resource speci‐
	    fications, or NULL.

  num_args  Specifies the number of arguments in the argument list.

Outputs
  base	    Returns the resource  values  from	the  argument  list,  the
	    resource database, or the resource list defaults.

Description
  XtGetApplicationResources()  retrieves  resource settings that apply to
  an overall application, rather than to a particular widget.	For  each
  resource  in	resources, XtGetApplicationResource() sets a value in the
  structure pointed to by base.	 This value comes from the argument  list
  args,	 or  if	 no value for the resource is found in the argument list,
  from the resource database associated with object, or if  no	value  is
  found	 in  the  database,  from  the default_addr field of the resource
  itself.  Once the value is determined, it is copied into the	structure
  at  base  using  the	resource_offset	 and  resource_size fields of the
  resource.

  The search  of  the  database	 is  done  using  the  resource_name  and
  resource_class  fields  of the resource.  Resources are searched for at
  the level in the resource name hierarchy at  which  object's	resources
  are  found,  i.e., application resources are set in a resource database
  in the same way as the specified object's resources are set.

  XtGetApplicationResources() may overwrite the specified  resource  list
  with	an equivalent representation in an internal format that optimizes
  access time if the list is used repeatedly.  The resource list must  be
  allocated  in	 writable storage and the caller must not modify the list
  contents after the call if the same list is to be used again.	 Any per-
  display  resources  fetched  by XtGetApplicationResources() will not be
  freed from the resource cache until the display is closed.

  The use of each of the fields in the XtResource structure is	explained
  in detail in the "Background" section below.

Usage
  Any  application that has any configurability should define application
  resources as an alternative to command line options  and  configuration
  files.   To  do this, you declare a structure that contains a field for
  each of the resource values you want to look up in the database.   Then
  you  statically  initialize  an  array  of  XtResource structures which
  describe the name, class, type and default of each resource,	and  also
  specify  the	size  of  the resource value and the location within your
  structure at which it should be stored.  Next	 you  call  XtGetApplica‐
  tionResources() with the address of your structure and your application
  resource list, and possibly an argument list of values to override  the
  database.   When  XtGetApplicationResources()	 returns,  your structure
  will be initialized with values from the argument  list,  the	 resource
  database,  or	 from  the resource list defaults.  The "Example" section
  below shows an example of this process, and  the  "Background"  section
  explains each of the fields of an XtResource structure in more detail.

  Usually, you will pass a the shell widget returned by XtAppInitialize()
  as  object.	This  will  make  XtGetApplicationResources()	look   up
  resources  of the form application_name.resource_name.  You may use any
  other widget or object, but this will make  XtGetApplicationResources()
  look	up  resources  that  are  deeper in the hierarchy, resources that
  appear to be resources of the specified widget.

Example
  Here is a short program that declares and  initializes  an  application
  resource  list  and  uses  it	 to  get  the  value  of some application
  resources.

     #include <X11/StringDefs.h>
     #include <X11/Intrinsic.h>

     /*
      * fields to be filled in from resources
      */
     typedef struct {
	 Pixel highlight_color;
	 XFontStruct *bold_font;
	 Boolean palette_on_left;
     } application_variable_rec;

     static XtResource resources[] = {
	 {"highlightColor", XtCForeground, XtRPixel, sizeof(Pixel),
	  XtOffsetOf(application_variable_rec, highlight_color),
	  XtRString, XtDefaultForeground
	 },
	 {"boldFont", XtCFont, XtRFontStruct, sizeof(XFontStruct *),
	  XtOffsetOf(application_variable_rec, bold_font),
	  XtRString, XtDefaultFont
	 },
	 {"paletteOnLeft", "PaletteOnLeft", XtRBoolean, sizeof(Boolean),
	  XtOffsetOf(application_variable_rec, palette_on_left),
	  XtRImmediate, True
	 }
     };

     main(argc, argv)
     int argc;
     char **argv;
     {
	 XtAppContext app_context;
	 Widget toplevel;
	 application_variable_rec app_vars;

	 toplevel = XtAppInitialize(&app_context, "XDraw",
				    NULL, 0, &argc, argv,
				    NULL, NULL, 0);

	 XtGetApplicationResources(toplevel,		 /* widget */
				   &app_vars,		 /* base address */
				   resources,		 /* resource list */
				   XtNumber(resources),	 /* how many */
				   NULL, 0);		 /* ArgList */
	  .
	  .
	  .
     }

  If the application name is "xdraw", then the application resources  can
  be set with lines like the following in a resource file:

     xdraw.highlightColor: blue
     xdraw.boldFont: *-helvetica-bold-r-*-*-*-180-*
     xdraw.paletteOnLeft: False

Background
  To  use  XtGetApplicationResources(),	 you  must initialize an array of
  XtResource structures which describe the resources you want to  obtain.
  The  XtResource  structure  is shown in the "Structures" section below.
  The fields of this structure are used as follows:

  resource_name
    This field specifies the name of the resource, i.e.,  the  name  that
    must  appear in a resource file to set this resource.  By convention,
    the first letter of a resource name is lowercase, and any  subsequent
    words  are	capitalized  and  concatenated without a hyphen or under‐
    score-"background"	and  "backgroundPixmap",  for  example.	  If  you
    define  a  symbolic	 constant for the resource name, it should be the
    same as the resource name, with a prefix, which should  end	 with  an
    `N'-XtNbackground  or  XmNbackgroundPixmap,	 for example.  It is also
    convention that the field in which	this  resource's  value	 will  be
    stored  has	 the  same name as the resource, using all lowercase let‐
    ters,  and	underscores  to	 separate  words--background  and   back‐
    ground_pixmap,  for	 example.  Resource names beginning with "xt" are
    reserved by the Intrinsics.

  resource_class
    This field specifies the class name of the resource.  If a number  of
    resources  have the same class, you can specify a value for all those
    resources with a single line in a resource	file.	The  "normalFont"
    and	 "boldFont" resources might both be of class "Font", for example.
    Class names conventionally begin with capital letters, and,	 as  with
    resource  names, subsequent words are capitalized and underscores are
    not used.  Symbolic names for class names are conventionally  spelled
    the	 same  way  as	the  class  name  with	a  prefix which ends with
    `C'--XtCFont, for example.	If there is no general	category  to  use
    for	 a resource's class, the class should be the same as the resource
    name, but capitalized.  Class names beginning with "Xt" are	 reserved
    by the Intrinsics.

  resource_type
    This  field is a string that identifies the type of the resource.  By
    convention, it is spelled the same way as the type of the field  that
    this  resource  will set, but begins with a capital letter.	 Symbolic
    names for resource types are spelled the same as the type  name,  but
    begin  with	 a prefix which end with `R'--XtRInt and XmRFontList, for
    example.  The Intrinsics predefine a number of types which are  shown
    in	the  table below.  Type names are used to identify which resource
    converter should be used to convert a string value from the	 resource
    database  into the appropriate type.  If one of your fields is not of
    one of the standard types listed below, use a type of your	own,  but
    be	aware that you will have to write and register a converter proce‐
    dure if you want to get values for that field from the resource data‐
    base.

  resource_size
    This field specifies the size in bytes of the field in your structure
    that this resource will set.  Use the sizeof()  operator  to  compute
    this value.

  resource_offset
    This  field	 specifies  the	 offset of this resource's field from the
    beginning of the structure.	 This value is added to the base argument
    passed to XtGetApplicationResources() in order to determine where the
    resource value is to be stored.  This field	 plus  the  resource_size
    field  provide  enough  information	 to  correctly store the resource
    value.  Use the XtOffsetOf() macro to determine the offset of a field
    in a structure.

  default_type
    This is a string which specifies the type of the default value in the
    default_addr field.	 It is the same sort of type as the resource_type
    field  explained  above.  The type of the default does not have to be
    the same as the type of resource.  If they do not match, an appropri‐
    ate	 resource  converter will be invoked to convert the default value
    when it is required.  In addition to the types listed  in  the  table
    below,  and	 any  types of your own definition, there are two special
    values  that  can  be  set	in  this  field.   If	default_type   is
    XtRImmediate,  then default_addr is interpreted as the resource value
    itself, rather than a pointer to  the  value.   This  is  useful  for
    resources  that  are  integers, Booleans,  or other scalar types.  If
    default_type is XtRCallProc, then default_addr is pointer to a proce‐
    dure  of  type XtResourceDefaultProc which is responsible for storing
    the default value in the correct  location.	  See  XtResourceDefault‐
    Proc(2) for details on the responsibilities of such a procedure.

  default_addr
    This  field specifies a pointer to the default value of the resource,
    which must be of the type identified by default_type.  This field  is
    interpreted		    differently		    for		    types
    XtRImmediate  and  XtRCallProc,  as	 explained   above.    Also,   if
    default_type  is  XtRString,  then default_addr is the string itself,
    not the address of the string (i.e., it is a char *, not a char **).

  The Intrinsics define symbolic names for a number of strings which rep‐
  resent  commonly  used  types.  These symbolic names and the types they
  represent are shown in the table below.

Resource Type	      C Type		Resource Type	      C Type
XtRAcceleratorTable   XtAccelerators	XtRInitialState	      int
XtRAtom		      Atom		XtRInt		      int
XtRBitmap	      Pixmap, depth=1	XtRLongBoolean	      long
XtRBoolean	      Boolean		XtRObject	      Object
XtRBool		      Bool		XtRPixel	      Pixel
XtRCallback	      XtCallbackList	XtRPixmap	      Pixmap
XtRCardinal	      Cardinal		XtRPointer	      XtPointer
XtRColor	      XColor		XtRPosition	      Position
XtRColormap	      Colormap		XtRScreen	      Screen*
XtRCursor	      Cursor		XtRShort	      short
XtRDimension	      Dimension		XtRString	      String
XtRDisplay	      Display*		XtRStringArray	      String*
XtREnum		      XtEnum		XtRStringTable	      String*
XtRFile		      FILE*		XtRTranslationTable   XtTranslations

XtRFloat	      float		XtRUnsignedChar	      unsigned char
XtRFont		      Font		XtRVisual	      Visual*
XtRFontSet	      XFontSet		XtRWidget	      Widget
XtRFontStruct	      XFontStruct*	XtRWidgetClass	      WidgetClass
XtRFunction	      (*)()		XtRWidgetList	      WidgetList
XtRGeometry	      char*		XtRWindow	      Window

Structures
  XtResource is defined as follows:

     typedef struct _XtResource {
	String	  resource_name;  /* Resource name */
	String	  resource_class; /* Resource class */
	String	  resource_type;  /* Representation type desired */
	Cardinal  resource_size;  /* Size in bytes of representation */
	Cardinal  resource_offset;/* Offset from base to put resource value */
	String	  default_type;	  /* Representation type of specified default */
	XtPointer default_addr;	  /* Address of resource default value */
     } XtResource, *XtResourceList;

  The ArgList type is defined as follows:

     typedef struct {
	 String	     name;
	 XtArgVal    value;
     } Arg, *ArgList;

See Also
  XtGetSubresources(1), XtOffsetOf(1).

Xt - Resource Management			   XtGetApplicationResources()
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net