source: mainline/uspace/lib/gui/widget.h@ a35b458

/*
 * Copyright (c) 2012 Petr Koupy
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - The name of the author may not be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/** @addtogroup gui
 * @{
 */
/**
 * @file
 */

#ifndef GUI_WIDGET_H_
#define GUI_WIDGET_H_

#include <adt/list.h>
#include <io/window.h>

struct window;
typedef struct window window_t;

struct widget;
typedef struct widget widget_t;

/**
 * Base class for all widgets. This structure should be first data member of
 * any derived widget structure.
 */
struct widget {
        link_t link;
        widget_t *parent;  /**< Parent widget of this widget. NULL for root widget. */
        list_t children;   /**< Children widgets of this widget. */
        window_t *window;  /**< Window into which this widget belongs. */
        const void *data;  /**< Custom client data. */

        sysarg_t hpos; /**< Horizontal position in window coordinates. */
        sysarg_t vpos; /**< Vertical position in window coordinates. */
        sysarg_t width;
        sysarg_t height;

        sysarg_t width_min;
        sysarg_t height_min;
        sysarg_t width_ideal; /**< Width size hint for initialization. */
        sysarg_t height_ideal; /**< Height size hint for initialization, */
        sysarg_t width_max;
        sysarg_t height_max;

        /**
         * Virtual destructor. Apart from deallocating the resources specific for
         * the particular widget, each widget shall remove itself from parents
         * children and deallocate itself. */
        void (*destroy)(widget_t *);

        /**
         * Reserved for bottom-top traversal when widget changes its properties and
         * want to inform its ancestors in widget hierarchy to consider rearranging
         * their children. As a reaction to this call, each widget shall fetch
         * information from its children and decide whether its own properties have
         * to be changed. If not, widget shall calculate new layout for its children
         * and call rearrange() on each of them. Otherwise, widget shall change its
         * own properties and call reconfigure() on its parent. */
        void (*reconfigure)(widget_t *);

        /**
         * Reserved for top-bottom traversal when widget decides to change layout
         * of its childer. As a reaction to this call, widget shall change its
         * position and size according to provided arguments, paint itself,
         * calculate new layout for its children and call rearrange() on each
         * of them. */
        void (*rearrange)(widget_t *, sysarg_t, sysarg_t, sysarg_t, sysarg_t);

        /**
         * As a reaction to window refresh event, widget hierarchy is traversed
         * in top-bottom order and repaint() is called on each widget. Widget shall
         * either paint itself or copy its private buffer onto window surface.
         * Widget shall also post damage event into window event loop. */
        void (*repaint)(widget_t *);

        /**
         * Keyboard events are delivered to widgets that have keyboard focus. As a
         * reaction to the event, widget might call reconfigure() on its parent or
         * rearrange() on its children. If the widget wants to change its visual
         * information, refresh event should be posted to the window event loop. */
        void (*handle_keyboard_event)(widget_t *, kbd_event_t);

        /**
         * Position events are delivered to those widgets that have mouse grab or
         * those that intersects with cursor. As a reaction to the event, widget
         * might call reconfigure() on its parent or rearrange() on its children.
         * If the widget wants to change its visual information, refresh event
         * should be posted to the window event loop. If the widget accepts
         * keyboard events, it should take ownership of keyboard focus. Widget can
         * also acquire or release mouse grab. */
        void (*handle_position_event)(widget_t *, pos_event_t);
};

/*
 * Note on derived widget constructor/destructor:
 * In order to support inheritance, wach widget shall provide init and deinit
 * function. These functions take already allocated widget and are responsible
 * for (de)initializing all widget-specific resources, inserting/removing the
 * widget into/from widget hierarchy and (de)initializing all data and functions
 * from the top-level base class defined above. For convenience, each widget
 * should also provide constructor to allocate and init the widget in one step.
 */

extern void widget_init(widget_t *, widget_t *, const void *);
extern void widget_modify(widget_t *, sysarg_t, sysarg_t, sysarg_t, sysarg_t);
extern const void *widget_get_data(widget_t *);
extern void widget_deinit(widget_t *);

#endif

/** @}
 */