The layers library provides three function calls for reordering layers:

    LONG BehindLayer ( long dummy, struct Layer *layer );
    LONG UpfrontLayer( long dummy, struct Layer *layer );
    LONG MoveLayerInFrontOf( struct Layer *layer_to_move,
                             struct Layer *other_layer );

behindlayer() moves a layer behind all other layers.  this function
considers any backdrop layers, moving a current layer behind all others
except backdrop layers.  upfrontlayer() moves a layer in front of all
other layers.  movelayerinfrontof() is used to place a layer at a specific
depth, just in front of a given layer.

As areas of simple refresh layers become exposed, due to layer movement or
sizing for example, the newly exposed areas have not been drawn into, and
need refreshing.  The system keeps track of these areas by using a
damagelist.  to update only those areas that need it, the beginupdate()
endupdate() functions are called.

    LONG BeginUpdate( struct Layer *l );
    void EndUpdate  ( struct Layer *layer, unsigned long flag );

beginupdate() saves the pointer to the current clipping rectangles and
installs a pointer to a set of cliprects generated from the damagelist in
the layer structure.  To repair the layer, use the graphics rendering
routines as if to redraw the entire layer, and the routines will
automatically use the new clipping rectangle list.  So, only the damaged
areas are actually rendered into, saving time.

    Never Modify the DamageList.
    ----------------------------
    The system generates and maintains the damagelist region.  all
    application clipping should be done through the installclipregion()
    function.

To complete the update process call endupdate() which will restore the
original cliprect list.