Module `Mlpost.Box`

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

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. The special points are kept

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 $tex.png$

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 _rect.png

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: Set the bounding path of a box

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: _west.png

val south_west : t -> Point.t

north _west.png

south _west.png

val north_east : t -> Point.t

south _west.png

north _east.png

val south_east : t -> Point.t

north _east.png

south _east.png

type vposition = [ | Command.vposition | `Custom of t -> Num.t ]
type hposition = [ | Command.hposition | `Custom of t -> Num.t ]
type position = [ | Command.position | `Custom of t -> Point.t ]

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 height of the box

return the width of the box

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

return the width of the box

shift pt x shifts the box x about the point pt

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

shift pt x shifts the box x about the point pt

center pt x centers the box x at the point pt

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

Draws a box

parameter 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. @img halign.png

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.

parameter min_width: minimum width of all boxes; default is zero

parameter 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

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

parameter min_width: minimum width of all boxes; default is zero

parameter same_width: if true, all boxes are of same width, and at least of min_width; default is false

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)).

parameter padding: horizontal padding used to separate the boxes; defaults to 0

parameter 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.

parameter padding: vertical padding used to separate the boxes

parameter 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.

parameter min_width: minimum width of all boxes; default is zero

parameter 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.

parameter min_height: minimum height of all boxes; default is zero

parameter 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 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 sub and a translation.

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 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 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