home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _bdbaf79c3295cc42a05440d9a8b82ad7 < prev    next >
Text File  |  2004-06-01  |  9KB  |  218 lines
  1. #  Copyright (c) 1990 The Regents of the University of California.
  2. #  Copyright (c) 1994-1996 Sun Microsystems, Inc.
  3. #  See the file "license.terms" for information on usage and redistribution
  4. #  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  5. #
  6. #
  7.  
  8. =head1 NAME
  9.  
  10. option - Using the option database in Perl/Tk
  11.  
  12. =for category Creating and Configuring Widgets
  13.  
  14. =head1 SYNOPSIS
  15.  
  16. S<    >I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>);
  17.  
  18. S<    >I<$widget>-E<gt>B<PathName>;
  19.  
  20. S<    >I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value > ?,I<priority>?);
  21.  
  22. S<    >I<$widget>-E<gt>B<optionClear>;
  23.  
  24. S<    >I<$widget>-E<gt>B<optionGet>(I<name, class>);
  25.  
  26. S<    >I<$widget>-E<gt>B<optionReadfile>(I<fileName> ?,I<priority>?);
  27.  
  28. =head1 DESCRIPTION
  29.  
  30. The option database (also known as the I<resource database> or the
  31. I<application defaults database>) is a set of rules for applying
  32. default options to widgets.  Users and system administrators can
  33. set up these rules to customize the appearance of applications
  34. without changing any application code; for example, a user might
  35. set up personal foreground and background colors, or a site
  36. might use fonts associated with visual or language preferences.
  37. Different window managers (and implementations of them) have implemented
  38. the database differently, but most Xt-based window managers use the
  39. I<.Xdefaults> file or the I<xrdb> utility to manage user preferences;
  40. some use both, and/or implement a more complex set of site, user and
  41. application databases.  Check your site documentation for these topics
  42. or your window manager's B<RESOURCE_MANAGER> property.
  43.  
  44. =head2 Being a good citizen
  45.  
  46. For most applications, the option database "just works."  The B<option...>
  47. methods are for applications that need to do something unusual, such as
  48. add new rules or test an option's default.  Even in such cases, the
  49. application should provide for user preferences.
  50. Do not hardcode widget options without a B<very> good reason.
  51. All users have their own tastes and they are all different.
  52. They choose a special font in a special size and have often spend a
  53. lot of time working out a color scheme that they will love until death.
  54. When you respect their choices they will enjoy working with your
  55. applications much more.  Don't destroy the common look and feel of a
  56. personal desktop.
  57.  
  58. =head2 Option rules and widget identification
  59.  
  60. All widgets in an application are identified hierarchically by I<pathname>,
  61. starting from the B<MainWindow> and passing through each widget used to create
  62. the endpoint.  The path elements are I<widget names>, much like the elements
  63. of a file path from the root directory to a file.  The rules in the option
  64. database are patterns that are matched against a widget's I<pathname> to
  65. determine which defaults apply.
  66. When a widget is created, the B<Name> option can be
  67. used to assign the widget's name and thus create a distinctive path
  68. for widgets in an application.  If the B<Name> option isn't given,
  69. Perl/Tk assigns a default name based on the type of widget; a
  70. B<MainWindow>'s default name is the B<appname>.  These defaults are fine
  71. for most widgets, so don't feel you need to find a meaningful name for
  72. every widget you create.
  73. A widget must have a distinctive name to allow users to tailor its
  74. options independently of other widgets in an application.  For instance,
  75. to create a B<Text> widget that will
  76. have special options assigned to it, give it a name such as:
  77.  
  78.   $text = $mw->Text(Name => 'importantText');
  79.  
  80. You can then tailor the widget's attributes with a rule in the option
  81. database such as:
  82.  
  83.   *importantText*foreground: red
  84.  
  85. The I<class> attribute identifies groups of widgets, usually within an
  86. application but also to group similar widgets among different applications.
  87. One typically assigns a class to a B<TopLevel> or B<Frame> so that the
  88. class will apply to all of that widget's children.  To extend the example,
  89. we could be more specific about the importantText widget
  90. by giving its frame a class:
  91.  
  92.   $frame = $mw->Frame(-class => 'Urgent');
  93.   $text = $frame->Text(Name => 'importantText');
  94.  
  95. Then the resource pattern can be specified as so:
  96.  
  97.   *Urgent*importantText*foreground: red
  98.  
  99. Similarly, the pattern C<*Urgent*background: cyan> would apply to all
  100. widgets in the frame.
  101.  
  102. =head1 METHODS
  103.  
  104. =over 4
  105.  
  106. =item I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>);
  107.  
  108. Identify a new widget with I<name> and/or I<class>.
  109. B<Name> specifies the path element for the widget; names generally begin with a
  110. lowercase letter.  B<-class> specifies the class for the widget and its
  111. children; classes generally begin with an uppercase letter.
  112. If not specified, Perl/Tk will assign a unique default name to each widget.
  113. Only B<MainWindow> widgets have a default class, made by uppercasing the
  114. first letter of the application name.
  115.  
  116. =item I<$widget>-E<gt>B<PathName>;
  117.  
  118. The B<PathName> method returns the widget's I<pathname>, which uniquely
  119. identifies the widget within the application.
  120.  
  121. =item I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value >?, I<priority>?);
  122.  
  123. The B<optionAdd> method adds a new option to the database.
  124. I<Pattern> contains the option being specified, and consists of
  125. names and/or classes separated by asterisks or dots, in the usual
  126. X format.  I<Value> contains a text string to associate with
  127. I<pattern>; this is the value that will be returned in calls to
  128. the B<optionGet> method.  If I<priority> is specified, it indicates
  129. the priority level for this option (see below for legal values);
  130. it defaults to B<interactive>. This method always returns an empty
  131. string.
  132.  
  133. =item I<$widget>-E<gt>B<optionClear>;
  134.  
  135. The B<optionClear> method clears the option database.  Default
  136. options (from the B<RESOURCE_MANAGER> property or the B<.Xdefaults>
  137. file) will be reloaded automatically the next time an option is
  138. added to the database or removed from it.  This method always returns
  139. an empty string.
  140.  
  141. =item I<$widget>-E<gt>B<optionGet>(I<name,class>);
  142.  
  143. The B<optionGet> method returns the value of the option specified for
  144. I<$widget> under I<name> and I<class>.  To look up the option,
  145. B<optionGet> matches the patterns in the resource database against
  146. I<$widget>'s I<pathname> along with the class of I<$widget>
  147. (or its parent if I<$widget> has no class specified).  The widget's
  148. class and name are options set when the widget is created (not
  149. related to class in the sense of L<bless>); the B<MainWindow>'s name
  150. is the B<appname> and its class is (by default) derived from the name
  151. of the script.
  152.  
  153. If several entries in the option database match I<$widget>'s I<pathname>,
  154. I<name>, and I<class>, then the method returns whichever was created with
  155. highest I<priority> level.  If there are several matching
  156. entries at the same priority level, then it returns whichever entry
  157. was I<most recently entered> into the option database.  If there are
  158. no matching entries, then the empty string is returned.
  159.  
  160. =item I<$widget>-E<gt>B<optionReadfile>(I<fileName>?,I<priority>?);
  161.  
  162. The B<optionReadfile> method reads I<fileName>, which should have the
  163. standard format for an X resource database such as B<.Xdefaults>, and
  164. adds all the options specified in that file to the option database.
  165. If I<priority> is specified, it indicates the priority level at which
  166. to enter the options;  I<priority> defaults to B<interactive>.
  167.  
  168. The I<priority> arguments to the B<option> methods are
  169. normally specified symbolically using one of the following values:
  170.  
  171. =over 8
  172.  
  173. =item B<widgetDefault>
  174.  
  175. Level 20.  Used for default values hard-coded into widgets.
  176.  
  177. =item B<startupFile>
  178.  
  179. Level 40.  Used for options specified in application-specific
  180. startup files.
  181.  
  182. =item B<userDefault>
  183.  
  184. Level 60.  Used for options specified in user-specific defaults
  185. files, such as B<.Xdefaults>, resource databases loaded into
  186. the X server, or user-specific startup files.
  187.  
  188. =item B<interactive>
  189.  
  190. Level 80.  Used for options specified interactively after the application
  191. starts running.  If I<priority> isn't specified, it defaults to
  192. this level.
  193.  
  194. =back
  195.  
  196. Any of the above keywords may be abbreviated.  In addition, priorities
  197. may be specified numerically using integers between 0 and 100,
  198. inclusive.  The numeric form is probably a bad idea except for new priority
  199. levels other than the ones given above.
  200.  
  201. =back
  202.  
  203. =head1 BUGS
  204.  
  205. The priority scheme used by core Tk is not the same as used by normal Xlib
  206. routines. In particular is assumes that the order of the entries is defined,
  207. but user commands like B<xrdb -merge> can change the order.
  208.  
  209. =head1 SEE ALSO
  210.  
  211. L<Tk::Xrm|Tk::Xrm>
  212.  
  213. =head1 KEYWORDS
  214.  
  215. database, option, priority, retrieve
  216.  
  217. =cut
  218.