Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/x/volume6/wsxc2/part01

Internet Message Format | 1990-04-26 | 24KB

Path: uunet!cs.utexas.edu!usc!apple!sun-barr!newstop!sun!auto-trol.COM
From: [e-mail] (Martin Brunecky)
Newsgroups: comp.sources.x
Subject: v06i095: WsXc -- poor man's UIL, Part01/03
Message-ID: <[e-mail]>
Date: 26 Apr 90 18:46:12 GMT
Sender: [e-mail]
Lines: 527
Approved: [e-mail]

Submitted-by: Martin Brunecky <[e-mail]>
Posting-number: Volume 6, Issue 95
Archive-name: wsxc2/part01

WsXc 2.0 Part 01/03

     WsXc - POOR MAN'S UIL, Release 2.0

     This posting contains the second release of  WsXc,  an  Xt Intrinsic
     extension alowing to specify the entire user interface within the  X
     resource database. Contrary to UIL, WsXc is very easy to use, and it
     is a lot of fun.

     This release uses a  completely  new syntax,  which we  have  found
     much closer to the Xt spirit then the original one. It also contains
     many enhancements and bug fixes.  WsXc  is provided on  as is basis,
     without any support or warranties.

     CONTENTS:

     o  README                 Basic description of the WsXc facility

     The basic description is a compromise between tutorial and reference
     manual, both of which are missing. For more details about individual
     functions, please refer to source code comments.

     The following files contain the code, based on Motif Xt  Intrinsics,
     tested  on  SPARC, Ultrix/RISC and VAX/VMS. The code is compatible
     with R4 Intrinsics, to use it with R3 Xt Intrisics requires to remove
     references to compositeObjectClass.

      o  WsCreate.h            defines available public functions
      o  WsCreateFunc.c        widget tree creation and control
      o  WsCvtStrToCallback.c  string to callback resource convertor

     The folowing demo applications use the WsXc code listed above,  and
     the Motif widget set. To change HellWorld to your widget set, simply
     modify the HelloWorld.c replacing Motif widgets with yours.
     Note, the application class resource files must be moved either into
     application-class directory, or your user preference files directory
     (HOME).

      o  HelloWorld.c          sample application
      o  HelloWorldClass       application class resource file
      o  WsRegisterMotif.c     registartion code for the Motif widget set
      o  MotifTest.c           more complex demo application
      o  MotifTestClass        application class resource file
      o  MotifTestMenu         class resource file for deffered load

WsXc 2.0 Part 01/03 contents:

      o  README                 Basic description of the WsXc facility
      o  WsCreate.h             defines available public functions
#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of shell archive."
# Contents:  README WsCreate.h
# Wrapped by marbru@auto-trol on Thu Apr 26 10:14:07 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'README' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'README'\"
else
echo shar: Extracting \"'README'\" \(16377 characters\)
sed "s/^X//" >'README' <<'END_OF_FILE'
X
X
X
X    POOR MAN's UIL - WsXc - RELEASE 2.0
X    -----------------------------------
X
X    About two weeks ago, prompted by the discussion  of  the  advantages
X    and  disadvantages  of UIL, I have put together some code supporting
X    user interface creation and management using SOLELY the  X  resource
X    database.  The preliminary code has been posted on comp.sources.x as
X    "WsXc".
X
X    Since then WsXc matured.  Besides the widget  set  independency  and
X    ability to define widget tree and callbacks within X resource files,
X    we have added several convenience callbacks, allowing to  deal  with
X    widgets  such  as  Attached Box (XmForm), postpone sub-tree creation
X    until the first action on it, and even postpone resource files  load
X    to reduce initialization time.
X
X    The existing experience, so  far,  is  very  positive.   Performance
X    benchmarks  show  that  WsXc  is  in-par  with UIL - slightly faster
X    widget fetches, slightly slower  inital  resource  file  load  (more
X    data).   Since  the  widget tree and all resource definitions are in
X    one place, WsXc can really take advantage of  resource  wildcarding,
X    significantly cutting down on the definition size.  Contrary to UIL,
X    there is no compilation step, making development iterations faster.
X
X    To better "fit" the X resource database concepts, we have completely
X    changed  WsXc  syntax.  We have added more (and better) diagnostics,
X    optional  widget  tree  creation  traceback,  trace   callback   for
X    development purposes, and fixed many bugs.
X
X
X    USING WsXc for USER INTERFACE DEFINITION
X    ----------------------------------------
X
X    To start, let me present a simple example of an application-class  X
X    resource file for a fancier flavor of HelloWorld:
X    !
X    !  shell - an application shell, contains RowColumn organizer
X    !
X    HelloWorld.createChildren:  box
X    !
X    !  box -  the main container, contains label and button
X    !
X    *box.createClass:           xmRowColumnWidgetClass
X    *box.createChildren:        label,button
X    !
X    !  label
X    !
X    *label.createClass:         xmLabelWidgetClass
X    *label.labelString:         Hello, WORLD !
X    !
X    !  button
X    !
X    *button.createClass:        xmPushButtonWidgetClass
X    *button.labelString:        Push ME
X    *button.activateCallback:   push(Push again to EXIT)
X
X    Except for the top-level shell creation, there is NO widget creation
X    code in this HelloWorld.  The entire widget tree definition is shown
X    above.  Widget  tree  is  defined  by  createChild  and  createClass
X    resources,  and  recursively  created from the top level shell down.
X    Similarly, callbacks are defined  by  name,  and  (optional)  string
X    argument  passed  to  callback function as callback data.  Note this
X    example is a starting point:  It does NOT show all the functionality
X    such  as  defferred  subtree  creation,  manage/unmanage  callbacks,
X    etc...
X
X
X    WsXc 2.0 OVERVIEW
X    -----------------
X
X    WsXc is a set of Xt Intrinsics based routines,  callbacks,  resource
X    converters  and  reserved  resource names.  The following is a brief
X    overview of the facility, not a reference manual.
X
X    Resources
X
X    The  application  resources  defined  for  individual  widgets   and
X    interpretted  by WsXc calls and callbacks always start with "create"
X    prefix:
X
X     o  createChildren:   name[,name]...
X
X        Specifies parent's children.  Other children resources, such  as
X        widget  class must be provided with each child.  Note, primitive
X        (non-composite) widgets may have pop-up children, however,  such
X        children  are  not created automatically - must be created using
X        one of creation callbacks.  This  restriction  reduces  creation
X        overhead  by  skipping  database query for children of primitive
X        widgets.
X
X     o  createClass:      class_or_constructor_name rec ed
X
X        Specifies widget  class  or  constructor  (convenience  creation
X        routine), registered by the application.
X
X     o  createCallback:   callback_name[(client_data_string)][,name...]
X
X        Specifies the (list of) callback(s) to invoke after  the  widget
X        has  been  created.   Often  used  to deliver widget ID to other
X        widgets ( such as default button  ID,  or  Attached  Box  widget
X        resources ).
X
X     o  createNoAuto:     true/false (default = false)
X
X        Controls  automatic  widget  creation.   Normally,  widget  tree
X        creation  recursively  descends the tree and creates all widgets
X        defined in the database.  Widgets with createNoAuto  "true"  are
X        skipped  (similarly to popup children of primitive widgets), and
X        must be created by explicit creation  call  or  callback.   This
X        allows to deffer sub-tree creation.
X
X     o  createUnmanaged:   true/false (default = false)
X
X        Specifies whether a widget is created managed or unmanaged  (for
X        example, Motif pulldown menus must be created unmanaged).
X
X     o  createTraceback:   true/false (default = false)
X
X        Specifies whether a traceback information about widget  creation
X        is  printed  on  standard output.  Used to assist in widget tree
X        design, particularly when deferred creation or heavy wildcarding
X        is used.
X
X
X    Functions
X
X    The functions used by the application to interface with WsXc are  as
X    follows:
X
X     o  WsRegisterObjectClass ( app, name, widget_class )
X
X        This function registers object/widget class with WsXc, assigning
X        it  a  name  (string)  to  be  used  within X resource file.  By
X        convention, the string should match class name  (though  mapping
X        is case-insensitive).
X
X     o  WsRegisterConstructor ( app, name, widget_constructor )
X
X        This  function  registers  object/widget  constructor  (creation
X        routine)  with  WsXc,  assigning  it  a name (string) to be used
X        within X resource file.  By convention, the string should  match
X        function name (though mapping is case-insensitive).
X
X     o  WsRegisterCallback ( app, name, callback, default_tag )
X
X        This function  registers  an  application  callback  with  WsXc,
X        assigning  it a name (string) to be used within X resource file.
X        By convention, the string should  match  callback  name  (though
X        mapping is case-insensitive).
X
X     o  WsRegisterCreateCallbacks ( app )
X
X        This function registers all WsXc provided callbacks, along  with
X        the StringToCallback resource converter.
X
X     o  WsCreateKnownChildren ( top_level_shell )
X
X        This function performs widget tree creation,  using  information
X        provided  by the X resource database.  Starting at the specified
X        widget,  function  recursively  descends  the  widget  tree  and
X        creates  all widgets defined in the database.  Except for direct
X        ancestors of the specified  widget,  widgets  with  createNoAuto
X        resource "true" are skipped - such sub-tree can be created later
X        using creation callbacks.
X
X    Callbacks
X
X    The WsXc package includes several "convenience" callbacks,  used  to
X    complemet the static definition contained within X resource database
X    with runtime dynamics.  Callbacks refer to "widget_path",  a  widget
X    name  qualified by all it's ancestores up to, but not including, the
X    top level shell.  For each callback, the client_data  string  format
X    (as appears in X resource database) is shown:
X
X     o  WsCreateKnownChildrenCB   ( widget_path[,widget_path...] )
X
X        This callback creates known children of  named  widget(s).   The
X        createNoAuto  resource  is  ignored  for the first level (direct
X        ancestors) of named widget(s).  Callback can be used  to  create
X        popup children of a primitive widget.
X
X     o  WsCreateNamedChildCB      ( child_name, widget_path )
X
X        This callback creates a subtree starting with a specified  child
X        of  a named widget(s).  The createNoAuto resource is ignored for
X        the first level (direct ancestors) of named widget(s).  Callback
X        can be used to create popup children of a primitive widget.
X
X     o  WsManageNamedChildrenCB   ( widget_path[,widget_path...] )
X
X        This callback manages named widget(s)
X
X     o  WsUnmanageNamedChidrenCB  ( widget_path[,widget_path...] )
X
X        This callback unmanages named widget(s)
X
X     o  WsDestroyNamedChildrenCB  ( widget_path[,widget_path...] )
X
X        This callback destroys named widget(s)
X
X     o  WsSetWidgetResourceCB     ( resource, widget_path[,widget_path])
X
X        This callback sets invoking widget's ID in  prescribed  resource
X        of named widget(s)
X
X     o  WsSetNamedWidgetResourceCB (widget_path, resource, widget_path)
X
X        This callback sets named widget's ID in prescribed  resource  of
X        named widget(s)
X
X     o  WsLoadResourceFileCB      ( filename )
X
X        This callback loads and merges an additional resource file.  The
X        file  is  searched  for  in XAPPLRESDIR directory first, then in
X        XUSERRESDIR.  Both  files  will  be  loaded,  if  present,  user
X        preferences overriding application ones.
X        The $LANG environmental variable use is NOT supported (yet).
X
X    A "string to callback" converter is provided with the package.   The
X    converter  builds an XtCallbackList using registered callback names.
X    Any callback on the list may have an optional  string  argument.   A
X    pointer  to  the  string  is  used  as  callback client data.  If no
X    argument  (string)  is  provided,  the  default  client  data  value
X    provided  at  registration  time  is  used.   The  callback resource
X    specification in the X resource database has the following format:
X
X        callbackName:   callback__name[(args)][,callback__name[(args)]]...
X
X    where   callback_name   is   the   callback   name    assigned    by
X    WsRegisterCallback, and args presents an arbitrary string.
X
X
X    WsXc EXAMPLES
X    -------------
X    Two examples are provided  with  WsXc.   Note,  in  both  cases  the
X    application   class   resource  files  must  be  moved  either  into
X    application class resources directory,  or  user  preference  (home)
X    directory.
X
X     o  HelloWorld, using HelloWorldClass resource file
X
X        This is a very basic demonstration of WsXc concepts.   The  demo
X        is  based  on  Motif widgets, but can be easily converted to use
X        any other widget set.
X
X     o  MotifTest, using MotiftestClass, MotifTestMenu resource files
X
X        This demo attempts to demonstrate more sophisticated WsXc usage,
X        such as creating Motif pulldown menus, defining default buttons,
X        deffered sub-tree creation and deffered resource file load.
X
X
X
X    WsXc COMPARISON WITH UIL
X    ------------------------
X    The X resource database user interface definition, here (for lack of
X    better  names)  referred  to  as  WsXc, performs essentialy the same
X    function as UIL.  As a complete comparison with  UIL  is  a  complex
X    task,  here I mention only several important differences between UIL
X    and WsXc.
X
X    Implementation:
X    A UIL application uses multiple user  interface  definition  sources
X    (application  code,  UIL  file,  compiled UID file and an X resource
X    file).  WsXc requires only  application  code  and  the  X  resource
X    file(s),  and  the  application  code  can  be  limited  to callback
X    functions.  The UIL approach  is  based  on  a  compiler  generating
X    intermediate code which is interpreted by Mrm at runtime.  WsXc is a
X    pure runtime interpreter.
X
X    Portability:
X    UIL generated  UID  files  are  machine-specific,  which  may  cause
X    problems  in  heterogeneous  environments.  For each machine type in
X    the network, a different version of the UID file must be maintained.
X    WsXc uses strictly ASCII X resource files, avoiding many portability
X    problems.
X
X    Performance:
X    Since UIL uses pre-compiled, machine specific data, the widget  tree
X    creation  could  be  faster  than  that for WsXc.  However, even UIL
X    widget creation accesses the X resource database for  resources  NOT
X    explicitly  specified  by  the  UIL  file.  Since MOST resources are
X    usually NOT explictly specified, the overhead depends  more  on  the
X    Xrm  database  volume, than on the widget creation method used.  UIL
X    fetches access the UID file - file  overhead  appears  at  a  widget
X    creation  time.   WsXc accesses Xrm database - file overhead appears
X    at the application startup time (unless the deffered  database  load
X    is  used).   Limited  timing  tests  performed  sofar  show  minimal
X    differences between both methods - widget creation itself  dominates
X    the time.
X
X    Extensibility.
X    Adding new widgets to UIL, even with the new Motif WML facility,  is
X    not an easy process.  Adding new data types (resource representation
X    types) to UIL is  often  impossible.   On  the  contrary,  there  is
X    nothing  special  about adding additional widgets to WsXc.  The same
X    method also applies to adding new data types.  The only  requirement
X    is  the  addition  of  a  convertor from string to a particular data
X    type.
X
X    Syntax Checking:
X    The UIL compiler can perform rigorous  syntax  checking  for  widget
X    resources,  thus  assisting in user interface development.  WsXc can
X    not catch any syntax errors in  resource  name  specification,  such
X    resources  are  simply  ignored.   However, errors in resource value
X    specification can be caught by the resource converter.  In addition,
X    a  simple tool that acquires a widget's resource list and performs X
X    resource file syntax checking can be added.
X
X    Value Computations:
X    The UIL compiler can compute  the  geometry  of  individual  widgets
X    using  arbitrary  arithmetic  expressions.  Geometry values in the X
X    resource database can not, currently, contain expressions.  However,
X    using  cpp, a string substitution could be applied.  This limitation
X    is primarily a resource converter issue.  A more intelligent  string
X    to   integer   converter   could  evaluate  arithmetic  expressions,
X    including X  resource  database  value  substitution.   But,  in  my
X    opinion,  geometry  configuration  should  be  left  to the geometry
X    manager  widgets  and  never  hardcoded  by   any   user   interface
X    definition.
X
X    Non-widget Value Fetches:
X    UIL  allows  to  define  named  values,  and  retrieve  those   with
X    application  calls.   The  X  resource  database  provides  the same
X    facility, in addition allowing to qualify names by  a  pathname  and
X    use  wildcarding.   Also,  assuming resource converter availability,
X    there are no limitations as to what data types can be used.
X
X    Deffered  Intialization:   Both  UIL  and  WsXc  provide  tools  for
X    deffered  sub-tree  creation,  which reduces the application startup
X    time.   To  convert  an  application  designed  for  simple  startup
X    initialization  into deffered one, UIL requires both application and
X    UIL code changes.  The WsXc conversion  implies  splitting  resource
X    file and adding deffered load/creation convenience callbacks.
X
X    Resource Conversions:
X    UIL supports resource conversions  such  as  colors,  pixelmaps  and
X    compound strings.  Many of the conversions are performed at runtime,
X    using resource converters  -  the  same  ones  as  WsXc.   For  some
X    resources, such as Compound Strings, UIL compile time conversion can
X    provide some runtime savings.  However, support  of  wide  character
X    sets  may require a separate "compound string" file, generated using
X    a "compound string editor" and accessed using ASCII keys - both  for
X    UIL and WsXc, eliminating any UIL advantage.
X
X    Interactive User Interface Generator Tools Support:
X    Interactive tools for user interface creation are coming.   Most  of
X    them  already  use  X  resource  database  for  majority  of  widget
X    resources.  Widget tree creation is often handled by the  "C"  code,
X    or by UIL.  WsXc can provide viable alternative both to "C" code and
X    UIL - simple  to  generate,  simple  to  read  back  and  parse,  no
X    compilation nor linking steps.
END_OF_FILE
if test 16377 -ne `wc -c <'README'`; then
    echo shar: \"'README'\" unpacked with wrong size!
fi
# end of 'README'
fi
if test -f 'WsCreate.h' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'WsCreate.h'\"
else
echo shar: Extracting \"'WsCreate.h'\" \(2607 characters\)
sed "s/^X//" >'WsCreate.h' <<'END_OF_FILE'
X/*
X*******************************************************************************
X* Copyright 1990 by Auto-trol Technology Corporation, Denver, Colorado.
X*
X*                        All Rights Reserved
X*
X* Permission to use, copy, modify, and distribute this software and its
X* documentation for any purpose and without fee is hereby granted, provided
X* that the above copyright notice appears on all copies and that both the
X* copyright and this permission notice appear in supporting documentation
X* and that the name of Auto-trol not be used in advertising or publicity
X* pertaining to distribution of the software without specific, prior written
X* permission.
X*
X* Auto-trol disclaims all warranties with regard to this software, including
X* all implied warranties of merchantability and fitness, in no event shall
X* Auto-trol be liable for any special, indirect or consequential damages or
X* any damages whatsoever resulting from loss of use, data or profits, whether
X* in an action of contract, negligence or other tortious action, arising out
X* of or in connection with the use or performance of this software.
X*
X* SCCS_data: @(#)WsCreate.h 1.2(4/18/90)
X*
X* Include_name:
X*
X*     WsCreate.h
X*
X* Subsystem_group:
X*
X*     Window System
X*
X* Related_keywords:
X*
X*     Public Defines
X*
X* Include_description:
X*
X*     Public defines for the Window System  widget tree creation from
X*     the Xrm database.
X*
X* Include_history:
X*
X*   mm/dd/yy  initials  action
X*   --------  --------  -------------------------------------------------------
X*   04/04/90   marbru   updated, added new callbacks
X*   03/27/90   marbru   updated for new names
X*   03/02/90   marbru   created
X*
X*******************************************************************************
X*/
X#ifndef _WsCreate_h
X#define _WsCreate_h
X
X/* -- App context inquiry, should be part of Ws.h */
X
X#define WsInqAppContext(w)  XtWidgetToApplicationContext(w)
X
X/* -- Widget constructor registration routine */
X
Xextern void WsRegisterObjectClass     ();
Xextern void WsRegisterConstructor     ();
Xextern void WsRegisterCallback        ();
Xextern void WsRegisterCreateCallbacks ();
X
X/* -- Widget creation routine */
X
Xextern void WsCreateKnownChildren     ();
X
X/* -- Convenience callbacks */
X
Xextern void WsCreateKnownChildrenCB   ();
Xextern void WsCreateNamedChildCB      ();
Xextern void WsManageNamedChildrenCB   ();
Xextern void WsUnmanageNamedChidrenCB  ();
Xextern void WsDestroyNamedChildrenCB  ();
Xextern void WsSetWidgetResourceCB     ();
Xextern void WsSetNamedWidgetResourceCB();
Xextern void WsLoadResourceFileCB      ();
X
X#endif  /* _WsCreate_h */
END_OF_FILE
if test 2607 -ne `wc -c <'WsCreate.h'`; then
    echo shar: \"'WsCreate.h'\" unpacked with wrong size!
fi
# end of 'WsCreate.h'
fi
echo shar: End of shell archive.
exit 0

dan
----------------------------------------------------
O'Reilly && Associates   [e-mail] / [e-mail]
Opinions expressed reflect those of the author only.