Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
EDITRES(1)		    General Commands Manual		    EDITRES(1)

       editres - a dynamic resource editor for X Toolkit applications

       editres [ -toolkitoption	... ]

       Editres accepts all of the standard X Toolkit command line options (see
       X(7)).  The order of the	command	line options is	not important.

       Editres is a tool that allows users and application developers to  view
       the  full widget	hierarchy of any X Toolkit application that speaks the
       Editres protocol.  In addition, editres will help  the  user  construct
       resource	 specifications,  allow	 the user to apply the resource	to the
       application and view the	results	dynamically.  Once the user  is	 happy
       with  a	resource specification editres will append the resource	string
       to the user's X Resources file.

       Editres provides	a window consisting of the following four areas:

       Menu Bar			A set of  popup	 menus	that  allow  you  full
				access to editres's features.

       Panner			The  panner  allows  a	more  intuitive	way to
				scroll the application tree display.

       Message Area		Displays information to	 the  user  about  the
				action that editres expects of her.

       Application Widget Tree	This area will be used to display the selected
				application's widget tree.

       To begin	an editres session select the Get Widget Tree menu  item  from
       the  command  menu.  This will change the pointer cursor	to cross hair.
       You should now select the application you wish look at by  clicking  on
       any of its windows.  If this application	understands the	editres	proto-
       col then	editres	will display the application's widget tree in its tree
       window.	 If  the  application does not understand the editres protocol
       editres will inform you of this fact in the message area	 after	a  few
       seconds delay.

       Once  you  have	a widget tree you may now select any of	the other menu
       options.	The effect of each of these is described below.

       Get Widget Tree
	       Allows the user to click	on any	application  that  speaks  the
	       editres protocol	and receive its	widget tree.

       Refresh Current Widget Tree
	       Editres	only knows about the widgets that exist	at the present
	       time.  Many applications	create and destroy widgets on the fly.
	       Selecting this menu item	will cause editres to ask the applica-
	       tion to resend its widget tree, thus updating  its  information
	       to the new state	of the application.

	       For  example, xman only creates the widgets for its topbox when
	       it starts up.  None of the widgets for the manual  page	window
	       are  created  until the user actually clicks on the Manual Page
	       button.	If you retrieved xman's	widget	tree  before  the  the
	       manual  page is active, you may wish to refresh the widget tree
	       after the manual	page has been displayed.  This will allow  you
	       to also edit the	manual page's resources.

       Dump Widget Tree	to a File
	       For  documenting	 applications it is often useful to be able to
	       dump the	entire application widget tree to an ASCII file.  This
	       file  can  then be included in the manual page.	When this menu
	       item is selected	a popup	dialog is activated.  Type the name of
	       the file	in this	dialog,	and either select okay,	or type	a car-
	       riage-return.  Editres will now dump the	widget	tree  to  this
	       file.  To cancel	the file dialog, select	the cancel button.

       Show Resource Box
	       This command will popup a resource box for the current applica-
	       tion.  This resource box	(described in detail below) will allow
	       the user	to see exactly which resources can be set for the wid-
	       get that	is currently selected  in  the	widget	tree  display.
	       Only  one widget	may be currently selected; if greater or fewer
	       are selected editres will refuse	to pop up the resource box and
	       put an error message in the Message Area.

       Set Resource
	       This  command  will  popup  a  simple dialog box	for setting an
	       arbitrary resource on all selected widgets.  You	must  type  in
	       the  resource  name, as well as the value.  You can use the Tab
	       key to switch between the  resource  name  field	 the  resource
	       value field.

       Quit    Exits editres.

       The  Tree  menu	contains  several commands that	allow operations to be
       performed on the	widget tree.

       Select Widget in	Client
	      This menu	item allows you	to select any widget in	 the  applica-
	      tion;  editres will then highlight the corresponding element the
	      widget tree display.   Once  this	 menu  item  is	 selected  the
	      pointer  cursor  will  again  turn  to a crosshair, and you must
	      click any	pointer	button in the widget you  wish	to  have  dis-
	      played.	Since  some  widgets are fully obscured	by their chil-
	      dren, it is not possible to get to every widget  this  way,  but
	      this  mechanism  does give very useful feedback between the ele-
	      ments in the widget tree and those in the	actual application.

       Select All

       Unselect	All

       Invert All
	      These functions allow the	user to	select,	 unselect,  or	invert
	      all widgets in the widget	tree.

       Select Children

       Select Parents
	      These  functions select the immediate parent or children of each
	      of the currently selected	widgets.

       Select Descendants

       Select Ancestors
	      These functions select all parents or children of	 each  of  the
	      currently	selected widgets.  This	is a recursive search.

       Show Widget Names

       Show Class Names

       Show Widget IDs

       Show Widget Windows
	      When  the	 tree widget is	initially displayed the	labels of each
	      widget in	the tree correspond to the widget names.  These	 func-
	      tions  will  cause  the  label  of all widgets in	the tree to be
	      changed to show the class	name, IDs, or window  associated  with
	      each widget in the application.  The widget IDs, and windows are
	      shown as hex numbers.

       In addition there are keyboard accelerators for each of the Tree	opera-
       tions.	If  the	 input focus is	over an	individual widget in the tree,
       then that operation will	only effect that widget.  If the  input	 focus
       is  in  the Tree	background it will have	exactly	the same effect	as the
       corresponding menu item.

       The translation entries shown may be  applied  to  any  widget  in  the
       application.   If  that	widget	is a child of the Tree widget, then it
       will only affect	that widget, otherwise it will have the	same effect as
       the commands in the tree	menu.

       Flash Active Widgets
	      This  command is the inverse of the Select Widget	in Client com-
	      mand, it will show  the  user  each  widget  that	 is  currently
	      selected	in the widget tree, by flashing	the corresponding wid-
	      get in the application numFlashes	(three by  default)  times  in
	      the flashColor.

	      Key     Option			 Translation Entry
	      space   Unselect			 Select(nothing)
	      w	      Select			 Select(widget)
	      s	      Select			 Select(all)
	      i	      Invert			 Select(invert)
	      c	      Select Children		 Select(children)
	      d	      Select Descendants	 Select(descendants)
	      p	      Select Parent		 Select(parent)
	      a	      Select Ancestors		 Select(ancestors)
	      N	      Show Widget Names		 Relabel(name)
	      C	      Show Class Names		 Relabel(class)
	      I	      Show Widget IDs		 Relabel(id)
	      W	      Show Widget Windows	 Relabel(window)
	      T	      Toggle Widget/Class Name	 Relabel(toggle)

	      Clicking	button	1  on  a widget	adds it	to the set of selected
	      widgets.	Clicking button	2 on a widget deselects	all other wid-
	      gets  and	then selects just that widget.	Clicking button	3 on a
	      widget toggles its label between the widget's instance name  the
	      widget's class name.

       The  resource box contains five different areas.	 Each of the areas, as
       they appear on the screen, from top to bottom will be discussed.

       The Resource Line
	      This area	at the top of  the  resource  box  shows  the  current
	      resource	name exactly as	it would appear	if you were to save it
	      to a file	or apply it.

       The Widget Names	and Classes
	      This area	allows	you  to	 select	 exactly  which	 widgets  this
	      resource will apply to.  The area	contains four lines, the first
	      contains the name	of the selected	widget and all its  ancestors,
	      and  the	more  restrictive  dot (.) separator.  The second line
	      contains less specific the Class names of	each widget, and  well
	      as the less restrictive star (*) separator.  The third line con-
	      tains a set of special buttons called Any	Widget which will gen-
	      eralize  this level to match any widget.	The last line contains
	      a	set of special buttons called Any Widget Chain which will turn
	      the  single  level into something	that matches zero or more lev-

	      The initial state	of this	area is	the  most  restrictive,	 using
	      the  resource  names  and	 the  dot separator.  By selecting the
	      other buttons in this area you  can  ease	 the  restrictions  to
	      allow  more  and	more  widgets to match the specification.  The
	      extreme case is to select	all  the  Any  Widget  Chain  buttons,
	      which  will  match  every	 widget	 in  the application.	As you
	      select different buttons the tree	display	will  update  to  show
	      you  exactly  which  widgets  will  be  effected	by the current
	      resource specification.

       Normal and Constraint Resources
	      The next area allows you to select the name  of  the  normal  or
	      constraint resources you wish to set.  Some widgets may not have
	      constraint resources, so that area will not appear.

       Resource	Value
	      This next	area allows you	to enter  the  resource	 value.	  This
	      value  should  be	 entered exactly as you	would type a line into
	      your resource file.  Thus	it should contain  no  unescaped  new-
	      lines.   There  are  a  few special character sequences for this

	      \n - This	will be	replaced with a	newline.

	      \### - Where # is	any octal digit.  This will be replaced	with a
	      single  byte that	contains this sequence interpreted as an octal
	      number.  For example, a value containing	a  NULL	 byte  can  be
	      stored by	specifying \000.

	      \<new-line> - This will compress to nothing.

	      \\ - This	will compress to a single backslash.

       Command Area
	      This  area  contains  several command buttons, described in this

       Set Save	File
	      This button allows the user to modify file  that	the  resources
	      will  be	saved to.  This	button will bring up a dialog box that
	      will ask you for a filename; once	the filename has been entered,
	      either  hit carriage-return or click on the okay button.	To pop
	      down the dialog box without changing the save  file,  click  the
	      cancel button.

       Save   This button will append the resource line	described above	to the
	      end of the current save file.  If	no save	file has been set  the
	      Set  Save	 File  dialog box will be popped up to prompt the user
	      for a filename.

       Apply  This button attempts to perform a	XtSetValues call on  all  wid-
	      gets  that  match	 the resource line described above.  The value
	      specified	is applied directly to	all  matching  widgets.	  This
	      behavior	is  an	attempt	to give	a dynamic feel to the resource
	      editor.  Since this feature allows users to put  an  application
	      in  states it may	not be willing to handle, a hook has been pro-
	      vided to allow specific applications to  block  these  SetValues
	      requests (see Blocking Editres Requests below).

	      Unfortunately  due  to design constraints	imposed	on the widgets
	      by the X Toolkit and the Resource	Manager, trying	to  coerce  an
	      inherently static	system into dynamic behavior can cause strange
	      results.	There is no guarantee that the	results	 of  an	 apply
	      will be the same as what will happen when	you save the value and
	      restart the application.	This functionality is provided to  try
	      to  give you a rough feel	for what your changes will accomplish,
	      and the results obtained should be considered suspect  at	 best.
	      Having  said  that,  this	 is  one  of  the  neatest features of
	      editres, and I strongly suggest that you play with it,  and  see
	      what it can do.

       Save and	Apply
	      This  button combines the	Save and Apply actions described above
	      into one button.

       Popdown Resource	Box
	      This button will remove the resource box from the	display.

       The editres protocol has	been built into	the Athena Widget  set.	  This
       allows all applications that are	linked against Xaw to be able to speak
       to the resource editor.	While this provides great flexibility, and  is
       a useful	tool, it can quite easily be abused.  It is therefore possible
       for any Xaw  application	 to  specify  a	 value	for  the  editresBlock
       resource	 described  below,  to keep editres from divulging information
       about its internals, or to disable the SetValues	part of	the protocol.

       editresBlock (Class EditresBlock)
	       Specifies which type of blocking	 this  application  wishes  to
	       impose on the editres protocol.

       The accepted values are:

       all	      Block all	requests.

       setValues      Block  all  SetValues  requests.	 As  this  is the only
		      editres request that actually modifies the  application,
		      this  is in effect stating that the application is read-

       none	      Allow all	editres	requests.

       Remember	that these resources are  set  on  any	Xaw  application,  not
       editres.	 They allow individual applications to keep all	or some	of the
       requests	editres	makes from ever	succeeding.   Of  course,  editres  is
       also  an	 Xaw  application,  so	it  may	also be	viewed and modified by
       editres (rather recursive, I know), these commands can  be  blocked  by
       setting the editresBlock	resource on editres itself.

       For editres the available application resources are:

       numFlashes (Class NumFlashes)
	       Specifies  the  number  of times	the widgets in the application
	       will be	flashed	 when  the  Show  Active  Widgets  command  in

       flashTime (Class	FlashTime)
	       Amount of time between the flashes described above.

       flashColor (Class flashColor)
	       Specifies  the  color  used  to	flash  application widgets.  A
	       bright color should be used that	 will  immediately  draw  your
	       attention to the	area being flashed, such as red	or yellow.

       saveResourcesFile (Class	SaveResourcesFile)
	       This  is	 the file the resource line will be append to when the
	       Save button activated in	the resource box.

       In order	to specify resources, it is useful to know  the	 hierarchy  of
       the  widgets which compose editres.  In the notation below, indentation
       indicates hierarchical structure.   The	widget	class  name  is	 given
       first, followed by the widget instance name.

       Editres	editres
	    Paned  paned
		 Box  box
		      MenuButton  commands
			   SimpleMenu  menu
			   SmeBSB  sendTree
			   SmeBSB  refreshTree
			   SmeBSB  dumpTreeToFile
			   SmeLine  line
			   SmeBSB  getResourceList
			   SmeLine  line
			   SmeBSB  quit
		      MenuButton  treeCommands
			   SimpleMenu  menu
			   SmeBSB  showClientWidget
			   SmeBSB  selectAll
			   SmeBSB  unselectAll
			   SmeBSB  invertAll
			   SmeLine  line
			   SmeBSB  selectChildren
			   SmeBSB  selectParent
			   SmeBSB  selectDescendants
			   SmeBSB  selectAncestors
			   SmeLine  line
			   SmeBSB  showWidgetNames
			   SmeBSB  showClassNames
			   SmeBSB  showWidgetIDs
			   SmeBSB  showWidgetWindows
			   SmeLine  line
			   SmeBSB  flashActiveWidgets
		 Paned	hPane
		      Panner  panner
		      Label  userMessage
		      Grip  grip
		 Porthole  porthole
		      Tree  tree
			   Toggle  <name of widget in application>
			   TransientShell  resourceBox
			   Paned  pane
			   Label  resourceLabel
			   Form	 namesAndClasses
			   Toggle  dot
			   Toggle  star
			   Toggle  any
			   Toggle  name
			   Toggle  class
			   Label  namesLabel
			   List	 namesList
			   Label  constraintLabel
			   List	 constraintList
			   Form	 valueForm
			   Label  valueLabel
			   Text	 valueText
			   Box	commandBox
			   Command  setFile
			   Command  save
			   Command  apply
			   Command  saveAndApply
			   Command  cancel
			   Grip	 grip
		 Grip  grip

       DISPLAY to get the default host and display number.

	       to  get	the  name of a resource	file that overrides the	global
	       resources stored	in the RESOURCE_MANAGER	property.

	      specifies	required resources

       X(7), xrdb(1), Athena Widget Set

       This is a prototype, there are lots of nifty features I would  love  to
       add,  but  I  hope  this	will give you some ideas about what a resource
       editor can do.

       Chris D.	Peterson, formerly MIT X Consortium

X Version 11			 editres 1.0.6			    EDITRES(1)


Want to link to this manual page? Use this URL:

home | help