Containers Overview

All Vision2 containers inherit EV_CONTAINER

What is a container?

A container is a Vision2 widget that may contain other widgets. Some containers such as EV_CELL may only hold one widget while containers such as EV_BOX may hold multiple widgets. As a container is of type EV_WIDGET, this means that a container may be placed within a container. A list of the classes held within the container cluster can be found here. Windows inherit from EV_CELL and are therefore classed as containers also.

Note: Containers may only contain other widgets. Items may only be placed in certain primitives. For example, an EV_LIST_ITEM may be contained in an EV_LIST.

Inheritance from Base

Wherever possible, Vision2 containers reuse the container structures provided by Base. This provides three main advantages:

Familiarity for operations such as access, insertions and removals. Anybody who already uses Base should find it easy to adapt to using Vision2 containers.
The underlying structures used have been tried and tested for many years and their design has been proved to be robust and effective.
It provides powerful methods of querying the contents. In the original Vision library, you needed to keep reference to widgets as you could not query the contents of a container.

For example, EV_CONTAINER inherits BOX and COLLECTION. Descendents of EV_CONTAINER such as EV_BOX may also inherit other structures from Base.

Usage of Containers

The main role of a container is to position its children in a certain way, an EV_HORIZONTAL_BOX for example positions it children side by side along the horizontal axis, to get vertical stacking you would use an EV_VERTICAL_BOX.

An code example of adding widgets to a container is as follows.

add_to_container is
        -- Add 3 buttons to a hbox and then show in window.
    local
        a_window: EV_TITLED_WINDOW
        a_hbox: EV_HORIZONTAL_BOX
        a_button: EV_BUTTON
    do
        create a_window
        create a_hbox
        create a_button.make_with_text ("Button1")
        a_hbox.extend (a_button)
        a_hbox.extend (create {EV_BUTTON}.make_with_text ("Button2"))
        a_hbox.extend (create {EV_BUTTON}.make_with_text ("Button3"))
        a_window.extend (a_hbox)
        a_window.show
    end

The mapping of a Vision2 container interface is very close to that of containers in Base, such as a linked list.

To add a widget to a container call `extend'.
To remove a widget from the container call `prune'.
To empty a container call `wipe_out'.
To traverse the container, you can use features such as start, forth, item and off.

Note: When a widget is added to a container, the container is the parent of the widget.

Size of widget within a container

The size of a widget in a container is always at least its minimum size. By default, when a widget is added to a container it is expandable. This means that if the container gets bigger, the widget will expand to fit the extra space. This convenient functionality means that you don't have to worry about handling the size of the widget (such as when a user alters the size of a window) as this is all performed automatically. If, on the other hand, you decide you want the widget to remain at a certain size (its minimum size), EV_BOX contains the convenient call disable_item_resize.

Sizing of containers

As EV_CONTAINER is of type EV_WIDGET, the following facilities are provided for setting the minimum size : set_minimum_width, set_minimum_height and set_minimum_size. It is important to remember that as a general rule, the current size of a container is always at least the minimum size of all its contents.

Note: The exception to this is: EV_FIXED, EV_VIEWPORT and EV_SCROLLABLE_AREA which do actually allow their contents to be larger than their current size.