3. Overview

The purpose of mtMintKit is to make the development of SDL programs more rapid. This is done by providing facilities that are useful to most SDL programs such as interface widgets and functions.

Here is a diagram that illustrates the relationships between SDL, Mint, and the application program:

3.1 Interface Elements

Using the above diagram as a guide, the graphical user interface (GUI) elements work as follows:

  • The application program sets up a GUI by defining widgets using the Mint API.
  • Mint draws these widgets onto an SDL surface which is displayed on the screen.
  • The user interacts with SDL creating events such as mouse clicks or key presses.
  • Mint sends signals to the application program to indicate what the user is doing.

    3.1.1 Widgets

    Mint organises widgets into a tree-like structure, which is populated by the application program on demand. Here is a list of the core widgets:

    mintWindow The top level widget that holds everything.
    mintDialog This is a special widget that sits underneath mintWindow, with each Dialog being modal so that only the youngest Dialog can have input focus at any one time.
    mintLabel A label holds some text and displays it on screen.
    mintArrow An arrow points in a particular direction.
    mintImage The Image widget simply holds a bitmap SDL image.
    mintButton There are 3 types of button: basic, toggle, and radio toggle. Typically they hold a label, an arrow, or an image.
    mintRectangle This is a simple rectangle on the screen. It can have a border and a specific colour if prescribed.
    mintCanvas This is an empty widget which the user application must hook an expose signal to in order to display something on it. It is intended for use as a basis for custom widgets.

    Mint also provides a few convenience widgets that are built from using several of the above basic widgets:

    mintFrame A frame is a simple rectangle area with an optional title. Both the title and rectangle area can have a border.
    mintSlider Vertical and horizontal Slider's are useful for creating scrollbars or allowing users to input numbers in a given range.
    mintTabs Tabs allow multiple areas to exist in the same rectangular area. Users toggle between them with a group of radio buttons.
    Popup Menu's Popup menu's come in 3 forms: basic, option button, pulldown. A popup menu is basically a dialog containing a set of buttons.
    mintViewport A viewport is a rectangular area that has optional scrollbars if the child area of the view area is larger than the view area.

    General widget handling code is kept in mint_widget.c with the API in mint_widget.h.

    3.1.2 Main Loop

    Once the application program has built an interface, control is then passed to Mint in order to wait for events to happen (e.g. user interaction or timed delays). The main loop code is contained in the file mint_main.c.

    3.1.3 Signals

    Once Mint encounters an event then a signal is sent. The application program can catch these signals using callbacks to run a specific piece of code when that signal is sent by Mint. Signal code is contained in the file mint_signal.c with the API being in mint_signal.h.

    3.2 Utility Functions

    Mint provides facilities for general functions such as UTF-8 strings, fonts, timers, inifiles, and balanced binary trees.

    3.2.1 Strings

    Strings in Mint are stored internally as UTF-8. If the user application wishes to transfer any other type of string to a UTF-8 string this can be done via the API kept in mint_string.h.

    3.2.2 Fonts

    To display strings or text in a Mint application you will first need to open a font. By default Mint uses a 16x8 or 8x8 font. The API in mint_font.h also allows font files (such as TTF) to be opened via the FreeType library.

    3.2.3 Timers

    Timers are used to trigger callbacks to the user application after a specified delay. Details of this API are in mint_timer.h. The API also allows you to slow down the internal Mint delay (normally one thousandth of a second) if you are using very slow hardware.

    3.2.4 Inifiles

    Mint provides a very basic inifile API in mint_inifile.h. Inifiles are useful for storing application data for storing default user settings, and Mint does this by using a simple key/data pair. This API also has a few other useful functions such as getting the default user directory and loading a whole file into memory.

    3.2.5 Trees

    The API for balanced binary trees (BBT) is provided via mint_tree.h. The purpose of a BBT is to provide a simple way to store a key/data pair in a structure that is very quick to find that data at a later time. The inifile code is a practical example of how to use a BBT.

    3.3 Customization

    Customization is done by creating new widget structures and attaching new objects to those widgets via via mint_object.h. This customization can be implemented directly inside an application or via a C library so that these features can be shared between programs.

    3.3.1 Custom Widgets

    Custom widgets can be created by either using mint_widget_create directly or by using a mintCanvas to give visual feedback to the user and to handle events/signals.

    3.3.2 Custom Dialogs

    Custom dialogs can be created in the same way that popup menus are created.

    SourceForge.net Logo