Previous  Up  Next

Module Mlpost.Box

module Box: sig .. end

A Box is a rectangle with some content and a (not necessarily rectangular) frame. Boxes can be placed, aligned and modified.

Boxes

type t

The abstract type of boxes

Creating boxes

type style =
| Rect
| Circle
| RoundRect
| Patatoid
| Patatoid2
| Ellipse
| RoundBox
| Custom of (Num.t -> Num.t -> Num.t * Num.t * Path.t) 
type 'a box_creator = ?dx:Num.t ->
       ?dy:Num.t ->
       ?name:string ->
       ?brush:Brush.t ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t -> ?fill:Color.t -> 'a -> t

All functions used to create boxes take the following optional parameters : dx (resp. dy) is the horizontal (resp. vertical) padding between the box border and its contents ; name, if present, is associated with the box and can be used to retrieve it using get ; stroke is the color used to draw the outline of the box ; when equal to None, the outline will not be drawn ; pen is the pen used to draw the box's outline, if absent Brush.Pen.default is used ; fill, if present, is the color used to fill the box.

val empty : ?width:Num.t ->
       ?height:Num.t ->
       ?style:style ->
       ?name:string ->
       ?brush:Brush.t ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t -> ?fill:Color.t -> unit -> t

the empty box

val empty_from_box : ?style:style ->
       ?name:string ->
       ?brush:Brush.t ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t -> ?fill:Color.t -> t -> t

the empty box with the same position and dimension as the box

val pic : ?style:style -> Picture.t box_creator

pic p creates a new box containing the picture p

val path : ?style:style -> Path.t box_creator

path p creates a new box containing the path p

val tex : ?style:style -> string box_creator

tex s creates a new box containing the LaTeX string s

val box : ?style:style -> t box_creator

box b creates a new box containing the box b

val circle : t box_creator

circle pic creates a circle box containing the picture pic. Optional padding is given by arguments dx and dy; default is 2bp.

val ellipse : t box_creator

ellipse pic creates a elliptic box containing the picture pic. Optional padding is given by arguments dx and dy; default is 2bp

val rect : t box_creator

rect pic creates a rectangular box containing the picture pic. Optional padding is given by arguments dx and dy; default is 2bp.

val round_rect : t box_creator

round_rect pic creates a rectangular box containing the picture pic, with rounded corners. Optional padding is given by dx and dy; default is 2bp

val patatoid : t box_creator

patatoid pic creates an undefined, vaguely rectangular box containing the picture pic. It may happen that the content overlaps with the box.

val patatoid2 : t box_creator

patatoid2 pic creates an undefined, vaguely rectangular box containing the picture pic, which is guaranteed to be fully contained in the patatoid.

val round_box : t box_creator
val bpath : t -> Path.t

Get the bounding path of a box

Set the bounding path of a box

val set_bpath : Path.t -> t -> t

Special points on a box

val ctr : t -> Point.t
val north : t -> Point.t
val south : t -> Point.t
val west : t -> Point.t
val east : t -> Point.t
val north_west : t -> Point.t
val south_west : t -> Point.t
val north_east : t -> Point.t
val south_east : t -> Point.t
type vposition = [ `Bot
       | `Bottom
       | `Center
       | `Custom of t -> Num.t
       | `North
       | `South
       | `Top ] 
type hposition = [ `Center
       | `Custom of t -> Num.t
       | `East
       | `Left
       | `Right
       | `West ] 
type position = [ `Bot
       | `Bottom
       | `Bottomleft
       | `Bottomright
       | `Center
       | `Custom of t -> Point.t
       | `East
       | `Left
       | `Lowerleft
       | `Lowerright
       | `Lowleft
       | `Lowright
       | `North
       | `Northeast
       | `Northwest
       | `Right
       | `South
       | `Southeast
       | `Southwest
       | `Top
       | `Topleft
       | `Topright
       | `Upleft
       | `Upperleft
       | `Upperright
       | `Upright
       | `West ] 
val corner : position -> t -> Point.t
val opposite_position : position -> position

Return the opposite position of a position (west for east, southeast for northwest, center for center, ...).

Operators

val height : t -> Num.t

return the height of the box

val width : t -> Num.t

return the width of the box

val shift : Point.t -> t -> t

shift pt x shifts the box x about the point pt

val center : Point.t -> t -> t

center pt x centers the box x at the point pt

val draw : ?debug:bool -> t -> Command.t

Draws a box

debug : if set to to true, the bounding path and the center of the box are drawn as well, default is false
val group : ?style:style -> t list box_creator

group bl groups a list of boxes bl into a single box

Boxes alignment

val halign : ?pos:vposition ->
       Num.t -> t list -> t list

halign ~pos y l vertically moves the boxes in l such that the vertical position given by pos is equal to y. The default value of pos is `Center, so by default this function moves each box such that the y coordinate of its center is y. The horizontal position of each box is unchanged.

val valign : ?pos:hposition ->
       Num.t -> t list -> t list

the vertical counterpart of valign.

val hplace : ?padding:Num.t ->
       ?pos:position ->
       ?min_width:Num.t ->
       ?same_width:bool -> t list -> t list

hplace l places the boxes of l horizontally, from left to right following the order of list elements, without changing their vertical position.

min_width : minimum width of all boxes; default is zero
same_width : if true, all boxes are of same width, and at least of min_width; default is false
val vplace : ?padding:Num.t ->
       ?pos:position ->
       ?min_height:Num.t ->
       ?same_height:bool -> t list -> t list

the vertical counterpart of hplace

val hbox : ?padding:Num.t ->
       ?pos:position ->
       ?style:style ->
       ?min_width:Num.t ->
       ?same_width:bool -> t list box_creator

places the given boxes horizontally, aligning them horizontally, and returns a box containing these boxes as sub-components. Leave the first box at its place. hbox l actually gives the same result as group (hplace (halign l)).

padding : horizontal padding used to separate the boxes; defaults to 0
pos : used to determine the way boxes are aligned; defaults to `Center
val hbox_list : ?padding:Num.t ->
       ?pos:position ->
       ?min_width:Num.t ->
       ?same_width:bool -> t list -> t list

as hbox, but does not group the resulting boxes into a surrounding box; it returns the list of placed boxes instead. hbox_list l is equal to hplace (halign l).

val vbox : ?padding:Num.t ->
       ?pos:position ->
       ?style:style ->
       ?min_height:Num.t ->
       ?same_height:bool -> t list box_creator

aligns the given boxes vertically and returns a box containing these boxes as sub-components. Leave the first box at its place.

padding : vertical padding used to separate the boxes
pos : used to determine the way boxes are aligned
val vbox_list : ?padding:Num.t ->
       ?pos:position ->
       ?min_height:Num.t ->
       ?same_height:bool -> t list -> t list
val tabular : ?hpadding:Num.t ->
       ?vpadding:Num.t ->
       ?pos:Command.position ->
       ?style:style ->
       ?name:string ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t ->
       ?fill:Color.t -> t array array -> t

aligns the given boxes both vertically and horizontally and returns a box containing all these boxes (with rows as first sub-components, and then individual boxes as sub-components of each row). Columns (resp. rows) are separated by hpadding (resp. vpadding); both default to 0. Alignment within columns and rows is controlled using pos. The arrays for rows must have the same lengths; otherwise Invalid_argument is raised.

val tabularl : ?hpadding:Num.t ->
       ?vpadding:Num.t ->
       ?pos:Command.position ->
       ?style:style ->
       ?name:string ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t ->
       ?fill:Color.t -> t list list -> t

similar to tabular, but using lists instead of arrays

val tabulari : ?hpadding:Num.t ->
       ?vpadding:Num.t ->
       ?pos:Command.position ->
       ?style:style ->
       ?name:string ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t ->
       ?fill:Color.t ->
       int -> int -> (int -> int -> t) -> t

similar to tabular, but using a matrix defined with a function

val hblock : ?padding:Num.t ->
       ?pos:Command.position ->
       ?name:string ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t ->
       ?min_width:Num.t ->
       ?same_width:bool -> t list -> t

hblock bl aligns the boxes of bl horizontally and surround them with new rectangular boxes of the same height; all these new boxes are packed together into the returned box.

min_width : minimum width of all boxes; default is zero
same_width : if true, all boxes are of same width, and at least of min_width; default is false
val vblock : ?padding:Num.t ->
       ?pos:Command.position ->
       ?name:string ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t ->
       ?min_height:Num.t ->
       ?same_height:bool -> t list -> t

similar to hblock, with vertical alignment.

min_height : minimum height of all boxes; default is zero
same_height : if true, all boxes are of same height, and at least of min_height; default is false
val grid : ?hpadding:Num.t ->
       ?vpadding:Num.t ->
       ?pos:Command.position ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t -> t array array -> t

Aligns the given boxes in a way that is similar to hblock and vblock: boxes are aligned in a grid where all cells have the same size. Each one of these cells is a box containing the original corresponding box.

val gridl : ?hpadding:Num.t ->
       ?vpadding:Num.t ->
       ?pos:Command.position ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t -> t list list -> t

similar to grid, but using lists instead of arrays

val gridi : ?hpadding:Num.t ->
       ?vpadding:Num.t ->
       ?pos:Command.position ->
       ?stroke:Color.t option ->
       ?pen:Pen.t ->
       ?dash:Dash.t ->
       int -> int -> (int -> int -> t) -> t

similar to gridi, but using a matrix defined with a function

val place : position ->
       ?pos:position ->
       ?padding:Num.t -> t -> t -> t

Place a box relatively to another box.

place `East a is a function which places a box at the east of a. Thus, place `East a b returns a copy of b placed at the east of a.

place posa ~pos: posb ~padding a b returns a new box c which is obtained by moving b to place the posa point of a on top of the posb point of b, and then padding the result by padding in direction posa.

Default value of posb is the opposite direction of posa wrt. the center (see Box.opposite_position). Default value of padding is zero.

The padding argument multiplies a unit vector which goes from the center of a to the corner of a indicated by posa. This effectively places point posa of a at exactly padding units of point posb of b, in direction posa. This also means that for diagonal directions, the actual direction will change according to the width / height ratio of a.

val relative : t -> t -> t

After using one of the previous function which give you a group g of box from multiple box (one of them must be b), you can use relative b g to translate g so that b inside g is at the same place than before. Indeed it's just Box.sub and a translation.

Box.relative is really useful when someone make a slideshow from a succession of figures.

Sub-boxes accessors

val nth : int -> t -> t

nth i b returns the i-th sub-box of b. The first sub-box has index 0. Raises Invalid_argument if there is no such sub-box.

val get : string -> t -> t

get n b returns the sub-box of b of name n, if any, and raises Invalid_argument otherwise. The behavior is not specified if b contains several sub-boxes with name n.

val sub : t -> t -> t

sub b1 b returns the sub-box of b which has the same name as b1, if any, and raises Invalid_argument otherwise. The behavior is not specified if b contains several sub-boxes with the name of b1.

val elts : t -> t array

elts b returns the sub-boxes of b; returns the empty array for the empty box or a box containing a picture.

Specials Points

val setp : string -> Point.t -> t -> t
val getp : string -> t -> Point.t
val getpx : string -> t -> Num.t
val getpy : string -> t -> Num.t

Box properties

val get_fill : t -> Color.t option
val set_fill : Color.t -> t -> t
val get_stroke : t -> Color.t option
val set_stroke : Color.t -> t -> t
val clear_stroke : t -> t
val get_name : t -> string option
val set_name : string -> t -> t
val get_pen : t -> Pen.t option
val set_pen : Pen.t -> t -> t
val set_height : Command.vposition -> Num.t -> t -> t
val set_width : Command.hposition -> Num.t -> t -> t
val get_dash : t -> Dash.t option
val set_dash : Dash.t -> t -> t
val clear_dash : t -> t
val set_height2 : vposition ->
       Num.t ->
       vposition -> Num.t -> t -> t

set_height2 `North y1 `South y2 b return the box b with its height and center chosen such as the ordinate of the top (because of `North) of the box is at y1 and the ordinate of its south is at y2

val set_width2 : hposition ->
       Num.t ->
       hposition -> Num.t -> t -> t
val set_size : Command.position ->
       width:Num.t -> height:Num.t -> t -> t
val same_height : ?pos:vposition -> t list -> t list
val same_width : ?pos:hposition -> t list -> t list
val same_size : ?pos:position -> t list -> t list
val henlarge : t list -> t list

henlarge l set the west boundaries of the box in l to the westest boundaries of the box in l. same for the east boundaries

val venlarge : t list -> t list

same as Box.henlarge for vertical boundaries

val set_post_draw : (t -> Command.t) -> t -> t
val add_post_draw : (t -> Command.t) -> t -> t
val clear_post_draw : t -> t
val set_pre_draw : (t -> Command.t) -> t -> t
val clear_pre_draw : t -> t

Misc.

val shadow : t -> t
val cpath : ?style:Path.joint ->
       ?outd:Path.direction ->
       ?ind:Path.direction ->
       ?sep:Num.t -> t -> t -> Path.t

the path that connects 2 boxes and stops at the box boundaries

val cpath_left : ?style:Path.joint ->
       ?outd:Path.direction ->
       ?ind:Path.direction ->
       ?sep:Num.t -> t -> Point.t -> Path.t

the path that connects a box and a point and stops at the box boundaries

val cpath_right : ?style:Path.joint ->
       ?outd:Path.direction ->
       ?ind:Path.direction ->
       ?sep:Num.t -> Point.t -> t -> Path.t

the path that connects a box and a point and stops at the box boundaries

val transform : Transform.t -> t -> t
val scale : Num.t -> t -> t
val rotate : float -> t -> t
val shift : Point.t -> t -> t
val yscale : Num.t -> t -> t
val xscale : Num.t -> t -> t

Boxlike : An argument for functor of object that are similar to box

val set_pos : Point.t -> t -> t

same as center