DOCUMENT ID:  1045-02

SYNOPSIS:     Frequently Asked Questions about OLIT

OS RELEASE:   

PRODUCT:      Solaris

KEYWORDS:     FAQ OLIT XVIEW


DESCRIPTION:

Frequently asked questions about OLIT

 0. What versions of OLIT are available?
 1. What are the differences between SunSoft's OLIT product and OLIT from USL?
 2. What are the differences between OLIT and XVIEW?
 4. What OLIT/Xt programming books/documentation exist?
 5. Where is there example OLIT code to look at?
 6. Are there any net news groups to post OLIT questions?
 7. When an OLIT application comes up, why is one widget an obnoxious red color?
 8. Why isn't my OLIT Application the same COLOR as all of my Desktop XView
    applications? (set by OpenWindows "Workspace Properties")
 9. Why do the OLIT widgets (buttons, scrollbars, etc.) look different from the
    objects in XView applications? (OLIT's are bigger!)
10. What widgets exist in OLIT? where I can see samples of all these widgets?
11. What are "FLAT" widgets? why would I want to use them?
13. How can I get Xt Translations to work for OLIT widgets?
14. How do I get notification in my OLIT application when the Quit/Dismiss
    option is selected off the system menu?
15. How are window decorations set on toplevel and popup shells?
16. When the PopupWindowShell is resized, the contents don't seem to respond to
    the resize - why?
17. Is it possible to write Internationalized applications using OLIT?
18. Is it possible to get OLIT source code?
19. How do XView objects/routines map to OLIT widgets/routines?
20. How do I set a color icon (more than fg/bg) for an OLIT application?


SOLUTION:

Q0. What versions of OLIT are available?

A0. The following lists the FCS OLIT toolkit versions out there today:

  . OLIT2.0: shipped with OpenWindows V2; based on older version of USL's Xt+
    toolkit; 2D only.

  . OLIT2.5: shipped unbundled; supports 2D & 3D objects; static libraries ONLY.

  . OLIT3.0: shipped with OpenWindows V3; superset of OLIT2.5 (see Question #3
    for details)

  . OLIT3.0.1: shipped with SunOS 5.0 (OpenWindows 3.0.1); SVR4 ONLY
    (equivalent to OLIT3.0 + bug fixes).  To take advantage of maximum bug
    fixes and features, we strongly recommend using at least OLIT3.0.


Q1. What are the differences between SunSoft's OLIT product and OLIT from USL?

A1.  OLIT was originally developed at AT&T (now USL) under the name of "Xt+".
     Sun's first version of OLIT was 2.0 (shipped with OpenWindows V2) and it
     was basically the same as USL's Release 2 (however Sun ported it to Xt
     R4); this was an early 2D-only release of OLIT.  Due to market pressure
     to ship 3D, Sun released OLIT2.5, which was based on USL's newer Release
     4 (included support for Xt R4, 3D & mouseless operation).  OLIT2.5 was,
     again, almost identical to USL's Release 4, plus Sun bug fixing.  OLIT
     3.0 (ships with OpenWindows V3) is a super-set of OLIT2.5.  It is
     USL's Release 4, plus the following Sun-ONLY features:

  . V3 Drag & Drop Support (DropTarget widget)
  . DrawArea Widget (supports 24 bit visuals)
  . Support for multiple displays
  . New toolkit initialization which supports fallback resources
  . MANY bugfixes!


Q2. What are the differences between OLIT and XVIEW?  Why might I want to use
    one over the other?)

A2. Both toolkits provide a means to render and manipulate a common set of
    OPEN LOOK UI objects. The major difference between the 2 toolkits is that
    OLIT is based on the MIT Xt Intrinsics (which is based on Xlib) while
    XView is based directly on Xlib and has an API more similar to Sunview.
    Each toolkit has benefits and drawbacks, and which to use depends on your
    application.


  [Note: this is based on XView3.0 and OLIT3.0 and may change slightly in
  future versions of the toolkits]

        Benefits of OLIT
        ----------------
  . It's based on Xt Intrinsics (considered a standard) - sometimes a
    requirement in government contracts.

  . Because it's based on Xt, it's API is similar to other Xt-based toolkits
    (Motif), and if an app must support both interfaces, source can be shared.

  . Provides a flexible layout scheme (OLIT allows much more flexibility in
    laying out objects than XView does -- Ex. panel items can be in ANY kind of
    container widget, aren't restricted to a "panel").

  . Provides "relative positioning" (you don't have to hardcode X,Y positions
    for objects).  Objects may be laid out relative to each other, so if one
    changes size (i.e.  it's label gets longer), everything will shift over
    correctly. (XView uses a lot of x,y positioning for layout).

  . Supports Xt Resource Management - most resources (attributes) for widgets
    can be specified OUTSIDE the application in resource files, such that they
    can be modified and the app doesn't not require recompilation to see the
    changes (XView3.0 supports this in a more limited scope).

  . Supports Dynamic resources -- if color/fonts are changed in the resource
    database, OLIT detects this and changes these in the *running* application
    (XView doesn't support this at all).


        Benefits of XView
        -----------------
  . It's API is similar to Sunview (if you're porting a sunview application,
    it's much easier to move to XView than to OLIT)

  . Easier to learn than OLIT (initial ramp-up time is less)

  . Provides high level packages for manipulating fonts, images, and colormaps
    (standard Xlib must be used for these in OLIT).

  . The source is freely available on the MIT Distribution (OLIT source is
    neither free, nor available on the MIT tape).

  . The OW DeskSet is built on XView - so apps developed in XView will look
    like the rest of the standard desktop (OLIT3.0 apps currently look slightly
    different because they use a different OPEN LOOK rendering library than
    XView).

  . A Level4 (Asian) Internationalized version of XView is available today
    (OLIT's is under development).


Q4. What OLIT/Xt programming books/documentation exist?

A4. Since OLIT is based on the Intrinsics, it's often necessary to have both
    OLIT Programming/Reference and Intrinsics Programming/Reference books.

  Note: This is neither an endorsement nor an exhaustive list; other books on
        the subject may also be available (see your favorite Tech bookstore!)

    Xt Intrinsics Documentation:

  1. X Window System Toolkit Comprehensive Programming Reference by Asente &
     Swick (available in Bookstores) Digital Press

  2. X Toolkit Programming, Volume4 Programming book (Athena based) by OReilly
     & Associates (available in Bookstores)

  3. X Toolkit Intrinsics, Volume5 API Reference by OReilly & Associates
     (available in Bookstores)

  Note: There may be other Intrinsics books available.

    OLIT Documentation:

  1. OLIT3.0 Reference Manual Only OLIT3.0 API Reference available by SunSoft,
     Inc. (Only available through SunSoft - part number: 800-6055-10)

  2. Programming Applications OLIT Programming Book with the Xt Intrinsics,
     (available in Bookstores) OPEN LOOK Addition by Young & Pew Prentice & Hall


Q5. Where is there example OLIT code to look at?

A5.  In OpenWindows 3.0, there is a lot of example OLIT code available:

  1. Examples from the Young & Pew programming book:
     OPENWINHOME/share/src/olit/olitbook

  2. Source for "olitsampler" demo: OPENWINHOME/share/src/olit/olitsampler

  3. Source for "oldials" demo: OPENWINHOME/share/src/olit/oldials

  4. "olittable" demo: has simple example code for each widget in its
     info-window, to start the demo: host% OPENWINHOME/demo/olittable&


Q6. Are there any net news groups to post OLIT questions?

A6. comp.windows.open-look is currently the available news group for posting
    OLIT questions.  If there is sufficient demand, a separate OLIT news group
    may be proposed.


Q7. When an OLIT application comes up, why is one widget an obnoxious red
    color? (how can I change/get rid of it?)

A7. Currently, this is OLIT's method for indicating where the mouseless focus
    is located (click on the arrow keys and you will see the red color move
    around).  This color is set by the resource, "XtNinputFocusColor", and can
    easily be changed in any resource file:
        *inputFocusColor: [desired-color-name]

    In future releases of OLIT (and also available in a patched version of
    OLIT3.0) there is an application resource, "XtNmouseless", which can be
    used to completely turn this off:
        *mouseless: FALSE

    The SuperCaret model for input focus is planned for a future release of
    OLIT.


Q8. Why isn't my OLIT Application the same COLOR as all of my Desktop XView
    applications? (set by Open Windows 3.0 Workspace Properties).

A8. OLIT uses the Xt method for reading resources from resource files and the
    resource database(see Resource chapter in an Intrinsics Programming manual
    and xrdb(1) for information on this), and the format for specifying
    resource values is different between Xt and other OpenWindows clients
    (XView & olwm).

    Resources written out by "WorkSpace Properties" in OpenWindows3.0 are in
    the format:
        OpenWindows.[resource]: [value]

    OLIT3.0 doesn't not have the mechanism to read in resources in this format.
    To set the colors for OLIT3.0 applications, try setting the following
    resources in a Resource file:
      *Background:            [window bg color]
      *foreground:            [window fg color]
      *fontColor:             [font color]

    In version of OLIT3.1 (SVR4 ONLY), OLIT will be able to read a subset of
    the OpenWindows.* format resources and this problem will be resolved.


Q9. Why do the OLIT widgets (buttons, scrollbars, etc) look different from the
    objects in XView applications? (OLIT's are bigger!)

A9. XView & olwm use a rendering library called "OLGX" (developed by Sun) to
    draw OPEN LOOK objects, while OLIT currently uses a different library
    called "Olg" (developed by USL).

                                                                                                     How are OLGX and Olg different?

    OLGX uses a glyph font (run "xlsfonts|grep glyph" and you'll see a number
    of these special glyph fontnames for different point sizes:
    "-sun-open look glyph-----10-100-75-75-p-106-unolglyph-1") to render
    objects (i.e. a round button corner is actually a character in this font),
    while Olg uses pure X drawing calls.

    XView/OLGX assume that 1 point = 1 pixel and so objects rendered to a 73x73
    DPI screen will appear smaller than their actual point size.  OLIT and Olg,
    however, convert points to pixels (based on the DPI of the screen), and
    therefore objects will be drawn approximately to scale and therefore appear
    larger.

    A future version of OLIT is planned to be based on OLGX - which will ensure
    that XView and OLIT applications look almost identical.


Q10. What widgets exist in OLIT? where I can see samples of all these widgets?

A10. Below is a brief Description of the widgets in OLIT3.0: Note: Working
     versions of most of these widgets can be seen in 2 demos:
        OPENWINHOME/demo/olitsampler
        OPENWINHOME/demo/olittable

  Containers (Managers used to layout widgets)
  . BulletinBoard    - allows simple x,y positioning of child widgets
  . ControlArea      - allows a row/column layout for child widgets
  . Form             - allows children to be relatively positioned to both the
                       window and other children within the window
  . RubberTile       - allows relative sizing for child widgets
  . FooterPanel      - provides a floating, fixed-height pane at bottom of
                       window
  . DrawArea         - can be used as a canvas for xlib drawing AND can have
                       other widget children placed at x,y locations
  . ScrolledWindow   - provides a window for vertical & horizontal scrolling of
                       another widget's contents.

  Controls
  . OblongButton     - push button
  . MenuButton       - push button with a menu attached
  . AbbrevMenuButton - an arrow button which brings up a menu
  . Exclusives       - one-of-many set of choice items
  . Nonexclusives    - n-of-many set of choice items
  . RectButton       - rectangular choice item
  . CheckBox         - label+checkmark choice item
  . FlatExclusives   - lite-weight one-of-many set of choices
  . FlatNonexclusives- lite-weight n-of-many set of choices
  . FlatCheckBox     - lite-weight n-of-many set of choices
  . Slider           - graphical display of numeric data
  . Gauge            - read-only graphical display of numeric data
  . Scrollbar        - an OPEN LOOK scrollbar
  . ScrollingList    - a vertical scrolling list of strings
  . DropTarget       - handles OW3.0 Drag&Drop src/dst operations
  . Stub             - handles to methods exposed, so behavior can be
                       customized without subclassing

  Gadgets (lighter weight because they share their parent's window)
  . OblongButton Gadget
  . MenuButton Gadget
  . AbbrevMenuButton Gadget

  Text
  . StaticText       - read-only text (Label)
  . TextField        - single line text entry field
  . TextEdit         - multi-line text edit window

  Shells
  . MenuShell        - standard popup menu
  . PopupWindowShell - popup window with built in "Apply","Reset",etc.
  . NoticeShell      - popup window to indicate message to user


Q11. What are "FLAT" widgets? why would I want to use them?

A11. Flat widgets are a method for implementing a group of 'like' subobjects
     within the context and datastructure of a single widget.  Flat  widgets
     are useful for implementing choice items (inside menus or  a panel) which
     have a large number of subitems or choices.

     The flat widgets can save significant memory by creating only one widget
     data structure & window for multiple sub-objects.  The flat widget API
     allows the programmer to decide which attributes (resources) of the
     sub-objects need to be distinctly different (i.e.label, font,etc) and
     store data structures containing only those distinct values for each
     sub-object, avoiding the duplication of much common data for each
     sub-object.

     For example, take the case of implementing an exclusive choice object
     which has 20 choices and only the label on each choice need be different:

        a) Using regular widgets:
                1 Exclusives Widget
                20 RectButton Widgets
                ---------------------
                21 client-side widget data structures
                21 server-side windows

        b) Using Flat widget:
                1 FlatExclusives Widget
                20 Strings to define distinct labels
                ------------------------------------
                1 client-side widget data structure + storage
                 for labels
                1 server-side window

      Disadvantages of Flat widgets are:
      - Difficult (or impossible) to set sub-object resource values outside the
        application in resource files
      - Non-standard API (and not portable to other Xt Toolkits)


Q13. How can I get Xt Translations to work for OLIT widgets?

A13. Below is an explanation of how these work in OLIT:


                          OLIT & Translations...

    Xt supports a translation mechanism which provides a method of mapping
    events (keystrokes, mousebuttons, etc) to toolkit actions.  Typically, a
    translation consists of an string which maps some event- syntax to a
    particular routine, called an "Action".  These translations are set on
    widgets, i.e. *textedit.translations:#override "Delete: delete_char()"

    When the Delete key is pressed in textedit, delete_char() will get called.
    (See Xt Programming documentation for more details on Xt Translation
    management and Action procedures).

    Now, Actions can be defined by the toolkit (for instance in Motif, a
    PushButton supports Arm(), Activate(), and Disarm() Actions) or by the
    application programmer (the above example creates a custom Action,
    "delete_char()").

    Programmers familiar with Motif or Athena expect that widgets have
    pre-defined toolkit Actions, and they become frustrated when they cannot
    find any Actions documented for OLIT widgets.  Well, this is because OLIT
    widgets only have a single translation.  Every event gets mapped to a
    single Action, OlAction(), which is internal to the toolkit.

    So, with OLIT, the user will not be able to set individual translations for
    pre-defined widget Actions, because there really aren't any (OlAction is
    very generic).  However, there is no reason why a programmer cannot create
    custom Actions in OLIT and then bind (or allow the user to bind)
    translations to those.

    If you have an OLIT TextEdit widget, and you want to have 1 translation for
    the Delete key which will override the TextEdit's handling of this key,
    (i.e. you don't want the widget to backspace on Delete) you could do the
    following:
        *textedit.translations:  #override Delete: my_delete_handler()

    Note: we've found that you must use "#override" to get this to work) where
    my_delete_handler is an Action routine you define yourself.

    If you want to create a translation for the BackSpace key where it both
    calls your custom Action IN ADDITION TO the TextEdit widget's handling of
    the backspace (i.e. you do want the widget to backspace) you do the
    following:
    *textedit.translations: #override BackSpace: OlAction() my_bs_handler()

    This ensures that the widget will first handle the backspace normally, and
    then your customer action will get called.

Q14. How do I get notification in my OLIT application when the Quit/Dismiss
     option is selected off the system menu?

A14. There is a special callback for shells, XtNwmProtocol, which allows the
     application to get called when a WM_PROTOCOL message is delivered to the
     application.  See Shell Resource Section in OLIT3.X Reference Manual for
     more detailed information on how to use this resource.


Q15. How are window decorations set on toplevel and popup shells?

A15. There are numerous Shells resources which allow easy configuration of the
     window decorations (which are displayed by olwm).  To name a few:
         XtNbusy - window header stipples as "busy"
         XtNmenuButton - display system menu button
         XtNpushpin - display pushpin
         XtNresizeCorners - display resize corners
         XtNwindowHeader - display window header

    See the Shell Resource Section in the OLIT 3.X  Reference Manual for
    further details on these resources.

Q16. When the PopupWindowShell is resized, the contents don't seem to respond
     to the resize - why?

A16. The PopupWindowShell is built using ControlArea widgets as its panes.
     ControlArea widgets do not propagate external resizes to their children,
     thus resizing the popup has no effect on widgets added inside it.

     The workaround to this problem is to use a standard TransientShell (See Xt
     Programming documentation for definition of a TransientShell) instead of a
     PopupWindowShell and then use a RubberTile or a Form as it's direct child
     (both of which deliver resizes to their children).  The catch to this
     approach is that you will have to add the "Apply","Reset", etc buttons to
     the popup and program in the automatic popdown behavior yourself (which is
     easy).

     Below are 2 code fragments - 1 showing how to create the popup, the 2nd
     showing the popdownCallback:

       /*************fragment 1*****************************/
        /*
         * Build  Custom Popup window
         */              transient =
        XtVaCreatePopupShell("transient",
        transientShellWidgetClass,
        toplevel,
             XtNtitle,      "I'm A Transient Window",
             XtNwinType,             OL_WT_CMD,
             XtNpushpin,             OL_OUT,
             XtNwindowHeader,        True,
             XtNmenuType,            OL_MENU_LIMITED,
             XtNresizeCorners,       True,
             XtNtransient,           True, NULL);

        /*
         * We'll use the RubberTile to ensure that it's children
         * Get resizes. (unlike the controlarea)
         */
        tile =  XtVaCreateManagedWidget("tile",
                        rubberTileWidgetClass,
                        transient,
                        XtNorientation, OL_VERTICAL,
                        NULL);

        /*
         * This is the pane where the bulk of the popupwindow
         * controls should go...
         */
        upperpane = XtVaCreateManagedWidget("upperpane",
                        formWidgetClass,
                        tile,
                        NULL);

        /*
         * This lower pane is solely for the "Apply","Cancel"
         * buttons which need to float at the bottom.
         */
        lowerpane = XtVaCreateManagedWidget("tile",
                        rubberTileWidgetClass,
                        tile,
                        XtNorientation, OL_HORIZONTAL,
                        XtNweight,      0, /* take no height changes */
                        NULL);

        XtVaCreateManagedWidget("padd",
                        staticTextWidgetClass,
                        lowerpane,
                        XtNweight,      4,
                        NULL);

        apply = XtVaCreateManagedWidget("Apply",
                        oblongButtonWidgetClass,
                        lowerpane,
                        XtNweight,      0,
                        NULL);

        XtVaCreateManagedWidget("padd",
                        staticTextWidgetClass,
                        lowerpane,
                        XtNweight,      2,
                        NULL);

        cancel = XtVaCreateManagedWidget("Cancel",
                        oblongButtonWidgetClass,
                        lowerpane,
                        XtNweight,      0,
                        NULL);

        XtVaCreateManagedWidget("padd",
                        staticTextWidgetClass,
                        lowerpane,
                        XtNweight,      4,
                        NULL);

        XtAddCallback(apply, XtNselect, popdownCB,
         transient);
        XtAddCallback(cancel, XtNselect, popdownCB,
         transient);


/******************fragment 2*******************************/
void
popdownCB(Widget w, Widget shell, caddr_t cd)
{
   OlDefine pin_state;

   XtVaGetValues(shell, XtNpushpin, &pin_state, NULL);

   if (pin_state == OL_OUT)
        XtPopdown(shell);
}
/***********************************************************/


Q17. Is it possible to write Internationalized applications using OLIT?

A17. OLIT2.5, OLIT3.0 & OLIT3.0.1 support I18N capabilities for Europe.  All
     these versions of OLIT are 8 bit clean, so it is possible to write an
     application which uses the ISO Latin-1 fonts.  Also, localizing strings
     can be accomplished via Resource files and since OLIT supports relative
     positioning in it's manager widgets, layout works for varying length
     strings. These versions of OLIT however do not have localized OLIT
     messages (errors, warnings, etc).

     A Level4 version of OLIT is being developed and will ship with the first
     Asian release of Solaris 2.X.

Q18. Is it possible to get OLIT source code?

A18. Currently, the only mechanism for obtaining OLIT3.0 source code is through
     purchasing the source code for OpenWindows3.0.

     This can be ordered via a local sales rep (Part Number OWSS-300-AS).  The
     current price is 5000.

Q20: How do I set a color icon (more than fg/bg) for an OLIT application?

A20: You can do this by creating an XWindow (where you'll paint whatever icon
     image you desire using Xlib calls) and set the Shell resource,
     XtNiconWindow, to that window.  Example Below.

/***********************************************************/
#include        
#include        
#include        

#include        
#include        
#include        

#include        "xpm.h"

static XpmAttributes CreatePixmapFromXpmData(Widget , char *, Pixmap *);


#define XPM_IMAGE "/home2/jmk/TMP/plaid.xpm"

main(argc, argv)
int   argc;
char *argv[];
{
        XtAppContext app;
        Widget  toplevel, container, button ;
        Window icon_window;
        Pixmap icon_pixmap;
        XpmAttributes xpm_attr;

        OlToolkitInitialize(NULL);
        toplevel = XtAppInitialize(&app, "icon", (XrmOptionDescList)NULL,
                        0,&argc, argv, (String *)NULL, (ArgList)NULL, 0);

        /* Create icon pixmap - using xpm */
        xpm_attr = CreatePixmapFromXpmData(toplevel, XPM_IMAGE, &icon_pixmap);

        /* Create icon-window & set its bg_pixmap to be the icon_pixmap.
         * Thus we avoid the need to redisplay the icon-window when
         * we get an expose-event .
         * Note that the icon_window MUST be a child of the Root window.
         * Ref ICCM Section 4, Client_to_WMgr-Commn , 4.1.9 for details
         */
        {
                unsigned long mask = CWBackPixmap;
                XSetWindowAttributes xattr;

                xattr.background_pixmap = icon_pixmap;
                icon_window =
                        XCreateWindow(
                        XtDisplay(toplevel),

          RootWindowOfScreen(XtScreenOfObject(toplevel)),
                        0 , 0,
                        xpm_attr.width, xpm_attr.height,
                        0,              /* border_width */
                        CopyFromParent, /* depth */
                        InputOutput,    /* class */
                        CopyFromParent, /* visual */
                        mask,
                        xattr);
        }

        /* Set the relevant resource for toplevel_shell */
        XtVaSetValues(toplevel, XtNiconWindow, icon_window, NULL);

        container =
        XtCreateManagedWidget("c1",controlAreaWidgetClass,
                                toplevel, NULL, 0);

        button =
    XtVaCreateManagedWidget("button",oblongButtonWidgetClass,
                                        container,
                                        XtNlabel, "Butts",
                                        NULL);

        XtRealizeWidget(toplevel);
        XtAppMainLoop(app);
}

static XpmAttributes
CreatePixmapFromXpmData(Widget w, char *file, Pixmap *pixmap)
{
        Pixmap shape_mask;
        static XpmAttributes attr;

        attr.visual = OlVisualOfObject(w);
        attr.depth = OlDepthOfObject(w);
        attr.colormap = OlColormapOfObject(w);
        attr.valuemask = XpmVisual | XpmColormap | XpmDepth;

        if (XpmReadFileToPixmap(
                XtDisplay(w),
                RootWindowOfScreen(XtScreenOfObject(w)),
                file,
                pixmap,
                &shape_mask,
                &attr) != XpmSuccess) {
                printf("Bummer!\n");
                exit(1);
        }
        return attr;
}
/***************END Example*********************************/


DATE APPROVED: 10/02/95