6.6 The group hierarchy and functions

The group hierarchy (g-hierarchy) is a structure of GOs in one page. If a GO is group, then its members are its g-children.

The G-hierarchy is an ordering over objects of the go kind in one page. This ordering can be also viewed as a rooted tree (where nodes are objects of the go kind and the root the of tree is the maximum of all nodes in that tree), so it is a join-semi-lattice.

Comparisions

These functions do the comparison of g-objects in the g-hierarchy. The root is the maximum.

(g<=? x1 x2)
go go -> boolean

(g>=? x1 x2)
go go -> boolean

(g<? x1 x2)
go go -> boolean

(g>? x1 x2)
go go -> boolean

Direct movement

These functions return the appropriate g-neighbours of a given object. Being a sibling is considered to be a reflexive relation.

(g-root x1)
go -> go

(g-parent x1)
go -> go + false

(g-first-child x1)
go -> go + false

(g-last-child x1)
go -> go + false

(g-first-sib go)
go -> go

(g-last-sib go)
go -> go

(g-next-sib go)
go -> go + false

(g-prev-sib go)
go -> go + false

The rest

(g-leaf? x)
any -> boolean
Returns whether the object x is a g-leaf. A g-leaf is member of the g-hierarchy which cannot have children (not just a g-object without g-children), i.e. a GO which is not of the group type.

(g-children x1)
go -> list
Returns the list of all g-children of x1. In unspecified order.

(g-ancestors x1)
go -> list
Returns the list of all g-ancestors of x1 (i.e. objects that are g-greater than x1). In descending g-order.

(g-descendants x1)
go -> list
Returns the list of all g-descendants of x1 (i.e. objects that are g-lesser than x1). It is ordered like the pre-order deep-first tree walk, so comparable objects are in descending g-order.

(g-leaves x1)
go -> list
Returns the list of all g-leaves that are g-lesser than x1. In unspecified order.

(g-set-parent! go grp)
go group -> unspecified
Sets grp as the new g-parent of go. It must be called in an appropriate transaction.

Because g-order and z-order is not completely independent, setting the g-parent also affects the z-order. This function tries to minimize the change. The next four functions allow a better control of z-change during the setting of a g-parent:

(g-set-parent/before go grp g2)
go group go -> unspecified
Like g-set-parent!, but go will be just before g2 in the z-order (g2 must be also a child of grp).

(g-set-parent/after go grp g2)
go group go -> unspecified
Like g-set-parent!, but go will be just after g2 in the z-order (g2 must be also a child of grp).

(g-set-parent/top go grp)
go group go -> unspecified
Like g-set-parent!, but go will be the minimal possible in the z-order.

(g-set-parent/bottom go grp)
go group go -> unspecified
Like g-set-parent!, but go will be the maximal possible in the z-order.