Layout.txt

Johannes Plass, plass@dipmza.physik.uni-mainz.de
-------------------------------------------------------------------------------

Overview:
---------------

This file is intended to document the changes made to the layout
widget.

The layout widget was written by Keith Packard and is available on:
   site: ftp.x.org
   file: R5contrib/Layout.tar.Z
The code of the original version of this widget may also be found
in this directory (the files lay*.c,lay*.h,lay*.l).
The layout semantics as well as syntax and interpretation of the
'layout' resource is described in the article Layout.ps
by Keith Packard. A copy of this article is supposed to be part
of this software. If not, it may be obtained from
   site: ftp.x.org
   file:  R5contrib/Layout-xconf93-paper.ps.Z
Further remarks on the layout semantics may be found below.

Modifications:
---------------

New resources:
   o 'resize'
   o 'conditionedResize'
   o 'maximumWidth', 'maximumHeight'
   o 'minimumWidth', 'minimumHeight'
   o constraint resource 'resizable'

Convenience Routines:
   o 'LayoutWidgetGetNaturalSize'
   o 'LayoutWidgetAllowResize'
   o 'LayoutWidgetSetSizeBounds'
   o 'LayoutWidgetGetSizeBounds'

The resources listed above have been introduced to allow for constraints on
the widget's geometry management that can not be realized by means of the
'layout' resource alone.
The default values of these resources represent the state of maximum 
compatibility with the original version of this widget.

Please note that despite the excellent geometry management
implemented by Keith Packard this widget has some weaknesses.
If its geometry manager is invoked in 'XtCWQueryOnly' mode
the widget always returns 'XtGeometryNo' if the requesting
child is interested in a possible new width, height or
border width.
Furthermore the layout widget never deals with its children
about their sizes, that is, the geometry manager never returns
'XtGeometryAlmost'.
Note also that the newly introduced resources have to be handled
with care.
 
Johannes Plass, December 1994

-------------------------------------------------------------------------------


Application Header File:   Layout.h
Class Header File:         LayoutP.h
class:                     layoutWidgetClass
Class:                     Layout
Superclass:                Constraint

Class specific Resources:
-------------------------


Name               Class          Type          Notes           Default Value
-------------------------------------------------------------------------------

debug              Boolean        Boolean                       False
layout             Layout         Layout                        NULL
maximumHeight      MaximumHeight  Dimension                     0
maximumWidth       MaximumWidth   Dimension                     0
minimumHeight      MinimumHeight  Dimension                     0
minimumWidth       MinimumWidth   Dimension                     0
resize             Boolean        Boolean                       True
conditionedResize  Boolean        Boolean                       True

debug:  If the value of this resource is 'True' a detailed description
        of the widget's geometry is written to 'stdout' whenever the layout 
        widget adjusts sizes and positions of its children.
layout: Determines how the layout widget manages its children.
        A detailed description of this resource is given in the article
        Layout.ps by Keith Packard.
maximumWidth, maximumHeight: Whenever the layout widget has the opportunity
        to address a geometry request to its parent the requested width and
        height will be bounded by the values of these resources. The requested
        width, height will be the minimum of the natural width, height and the
        maximumWidth, maximumHeight.
        Setting one of these values to '0' has a special meaning. In this case
        the layout widget's geometry considerations are free of any upper
        bounds in the given direction. 
        Setting this resources to non zero values affects the way how the 
        layout widget acts upon geometry requests of its children or changes
        in its list of managed children.
        These resources are adjusted automatically if the
        parent of the layout widgets forces a width or height that exceeds
        the current values of maximumWidth or maximumHeight.
minimumWidth, minimumHeight: These resources are the
        counterparts to the maximumWidth and maximumHeight resources
        and are interpreted analogously.
resizeWidth, resizeHeight: Determine the resize behaviour of the layout
        widget in the given direction.
        If one of these resources is 'False' the layout widget
        will never attempt to change its current size in the given direction.
        In this case children still may succesfully address resize requests
        to the layout widget, the layout widget,
        however, will never request a new size from its own parent to
        satisfy any wishes of its children. The same holds true if the
        widget's set of managed children changes.
        If one of these resources is 'True' the layout widget is allowed to
        ask its own parent for a new size in the given direction
        whenever it seems to be the apropriate step to satisfy wishes of its
        children.
conditionedResize: If the layout widget is allowed to resize and this resource
        is set to 'True' the layout widget will try to change its size only
        if its current size does not seem to be appropriate to achieve a
        satisfactory layout.
        If the layout widget is allowed to resize and this resource is set to 
        'False' the layout widget will try to resize whenever its current
        size differs from its natural size.

Constraint Resources:
---------------------

Each child of the layout widget is subject to additional 'constraint' 
resources.

Name            Class           Type            Notes           Default Value
------------------------------------------------------------------------------

resizable       Boolean         Boolean                         True

resizable: If this resource is 'False' for a specific child the layout widget
        will ignore all width, height and border width requests of this child. 


Convenience Routines:
---------------------

To obtain the desired size of the layout widget use

void LayoutWidgetGetNaturalSize(layoutwidget,width_ptr,height_ptr)
   LayoutWidget layoutwidget;
   Dimension *width_ptr;
   Dimension *height_ptr;

layoutwidget: specifies the layout widget
width_ptr   : where to store the natural width
height_tr   : where to store the natural height

----

A convenient way to set or get the values of the resources
minimumWidth, minimumHeight, maximumWidth, maximumheight
is provided by the convenience routines

LayoutWidgetGetSizeBounds(layoutwidget,minw_p,minh_p,maxw_p,maxh_p)
    LayoutWidget  layoutwidget;
    Dimension *minw_p;
    Dimension *minh_p;
    Dimension *maxw_p;
    Dimension *maxh_p;

layoutwidget: specifies the layout widget
minw_p,minh_p,maxw_p,maxh_p: specify the adresses into which
              the resource values are to be stored.
              If NULL is passed the value of the corresponding resource
              will not be returned.

LayoutWidgetSetSizeBounds(layoutwidget,minw_p,minh_p,maxw_p,maxh_p)
    LayoutWidget  layoutwidget;
    Dimension *minw_p;
    Dimension *minh_p;
    Dimension *maxw_p;
    Dimension *maxh_p;

layoutwidget: specifies the layout widget
minw_p,minh_p,maxw_p,maxh_p: specify the adresses of the new
              minimum width, minimum height maximum width, maximum height
              or NULL.
              If NULL is passed the corresponding resource will not
              be changed.

----

A convenient way to set the values of the resizeWidth and resizeHeight
resources is

LayoutWidgetAllowResize(layoutwidget,allow_horizontal,allow_vertical)
    LayoutWidget  layoutwidget;
    Boolean allow_horizontal;
    Boolean allow_vertical;

layoutwidget: specifies the layout widget
allow_horizontal,allow_vertical: specify the new values
              of the resizeWidth, resizeHeight resources.


Copyright:
----------

The sources of the layout widget (Layout.c,Layout.h,LayoutP.h) contain the
following copyright and permission notice:

/*
 * $XConsortium: Layout.c,v 1.1 91/09/13 18:51:44 keith Exp $
 * $XConsortium: Layout.h,v 1.2 92/01/22 18:03:05 keith Exp $
 * $XConsortium: LayoutP.h,v 1.2 92/01/22 18:03:08 keith Exp $
 *
 * Copyright 1991 Massachusetts Institute of Technology
 *
 * Permission to use, copy, modify, distribute, and sell this software and its
 * documentation for any purpose is hereby granted without fee, provided that
 * the above copyright notice appear in all copies and that both that
 * copyright notice and this permission notice appear in supporting
 * documentation, and that the name of M.I.T. not be used in advertising or
 * publicity pertaining to distribution of the software without specific,
 * written prior permission.  M.I.T. makes no representations about the
 * suitability of this software for any purpose.  It is provided "as is"
 * without express or implied warranty.
 *
 * M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL M.I.T.
 * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 
 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 * Author:  Keith Packard, MIT X Consortium
*/

