diff libvisual/lv_ui.h @ 23:0db4a1dc75c4 trunk

[svn] libvisual. P3 detection appears to be borked. I'll work on it later.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libvisual/lv_ui.h	Mon Oct 24 23:13:56 2005 -0700
@@ -0,0 +1,472 @@
+/* Libvisual - The audio visualisation framework.
+ * 
+ * Copyright (C) 2004, 2005 Dennis Smit <[e-mail]>
+ *
+ * Authors: Dennis Smit <[e-mail]>
+ *
+ * $Id:
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#ifndef _LV_UI_H
+#define _LV_UI_H
+
+#include <libvisual/lv_list.h>
+#include <libvisual/lv_param.h>
+#include <libvisual/lv_video.h>
+#include <libvisual/lv_common.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+#define VISUAL_UI_WIDGET(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_WIDGET, VisUIWidget))
+#define VISUAL_UI_CONTAINER(obj)			(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_CONTAINER, VisUIContainer))
+#define VISUAL_UI_BOX(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_BOX, VisUIBox))
+#define VISUAL_UI_TABLE_ENTRY(obj)			(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_TABLE, VisUITableEntry))
+#define VISUAL_UI_TABLE(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_TABLE, VisUITable))
+#define VISUAL_UI_FRAME(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_FRAME, VisUIFrame))
+#define VISUAL_UI_LABEL(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_LABEL, VisUILabel))
+#define VISUAL_UI_IMAGE(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_IMAGE, VisUIImage))
+#define VISUAL_UI_SEPARATOR(obj)			(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_SEPARATOR, VisUISeparator))
+#define VISUAL_UI_MUTATOR(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_MUTATOR, VisUIMutator))
+#define VISUAL_UI_RANGE(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_RANGE, VisUIRange))
+#define VISUAL_UI_ENTRY(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_ENTRY, VisUIEntry))
+#define VISUAL_UI_SLIDER(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_SLIDER, VisUISlider))
+#define VISUAL_UI_NUMERIC(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_NUMERIC, VisUINumeric))
+#define VISUAL_UI_COLOR(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_COLOR, VisUIColor))
+#define VISUAL_UI_CHOICE_ENTRY(obj)			(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_CHOICE, VisUIChoiceEntry))
+#define VISUAL_UI_CHOICE(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_CHOICE, VisUIChoice))
+#define VISUAL_UI_POPUP(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_POPUP, VisUIPopup))
+#define VISUAL_UI_LIST(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_LIST, VisUIList))
+#define VISUAL_UI_RADIO(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_RADIO, VisUIRadio))
+#define VISUAL_UI_CHECKBOX(obj)				(VISUAL_CHECK_CAST ((obj), VISUAL_WIDGET_TYPE_CHECKBOX, VisUICheckbox))
+
+/**
+ * Enumerate to define the different types of VisUIWidgets.
+ */
+typedef enum {
+	VISUAL_WIDGET_TYPE_NULL,	/**< NULL widget */
+	VISUAL_WIDGET_TYPE_WIDGET,	/**< Base widget: \a VisUIWidget. */
+	VISUAL_WIDGET_TYPE_CONTAINER,	/**< Container widget: \a VisUIContainer. */
+	VISUAL_WIDGET_TYPE_BOX,		/**< Box widget: \a VisUIBox. */
+	VISUAL_WIDGET_TYPE_TABLE,	/**< Table widget: \a VisUITable. */
+	VISUAL_WIDGET_TYPE_FRAME,	/**< Frame widget: \a VisUIFrame. */
+	VISUAL_WIDGET_TYPE_LABEL,	/**< Label widget: \a VisUILabel. */
+	VISUAL_WIDGET_TYPE_IMAGE,	/**< Image widget: \a VisUIImage. */
+	VISUAL_WIDGET_TYPE_SEPARATOR,	/**< Separator widget: \a VisUISeparator. */
+	VISUAL_WIDGET_TYPE_MUTATOR,	/**< Mutator base widget: \a VisUIMutator. */
+	VISUAL_WIDGET_TYPE_RANGE,	/**< Range base widget: \a VisUIRange. */
+	VISUAL_WIDGET_TYPE_ENTRY,	/**< Entry box widget: \a VisUIEntry. */
+	VISUAL_WIDGET_TYPE_SLIDER,	/**< Slider widget: \a VisUISlider. */
+	VISUAL_WIDGET_TYPE_NUMERIC,	/**< Numeric widget: \a VisUINumeric. */
+	VISUAL_WIDGET_TYPE_COLOR,	/**< Color widget: \a VisUIColor. */
+	VISUAL_WIDGET_TYPE_CHOICE,	/**< Choice base widget: \a VisUIChoice. */
+	VISUAL_WIDGET_TYPE_POPUP,	/**< Popup widget: \a VisUIPopup. */
+	VISUAL_WIDGET_TYPE_LIST,	/**< List widget: \a VisUIList. */
+	VISUAL_WIDGET_TYPE_RADIO,	/**< Radio widget: \a VisUIRadio. */
+	VISUAL_WIDGET_TYPE_CHECKBOX	/**< Checkbox widget: \a VisUICheckbox. */
+} VisUIWidgetType;
+
+/**
+ * Enumerate to define the different types of widget orientation. This is used
+ * by a few widgets that can be aligned both vertical and horizontal.
+ */
+typedef enum {
+	VISUAL_ORIENT_TYPE_NONE,	/**< No orientation, use the default. */
+	VISUAL_ORIENT_TYPE_HORIZONTAL,	/**< Horizontal orientation. */
+	VISUAL_ORIENT_TYPE_VERTICAL	/**< Vertical orientation. */
+} VisUIOrientType;
+
+typedef struct _VisUIWidget VisUIWidget;
+typedef struct _VisUIContainer VisUIContainer;
+typedef struct _VisUIBox VisUIBox;
+typedef struct _VisUITableEntry VisUITableEntry;
+typedef struct _VisUITable VisUITable;
+typedef struct _VisUIFrame VisUIFrame;
+typedef struct _VisUILabel VisUILabel;
+typedef struct _VisUIImage VisUIImage;
+typedef struct _VisUISeparator VisUISeparator;
+typedef struct _VisUIMutator VisUIMutator;
+typedef struct _VisUIRange VisUIRange;
+typedef struct _VisUIEntry VisUIEntry;
+typedef struct _VisUISlider VisUISlider;
+typedef struct _VisUINumeric VisUINumeric;
+typedef struct _VisUIColor VisUIColor;
+typedef struct _VisUIChoiceList VisUIChoiceList;
+typedef struct _VisUIChoiceEntry VisUIChoiceEntry;
+typedef struct _VisUIChoice VisUIChoice;
+typedef struct _VisUIPopup VisUIPopup;
+typedef struct _VisUIList VisUIList;
+typedef struct _VisUIRadio VisUIRadio;
+typedef struct _VisUICheckbox VisUICheckbox;
+
+/* FIXME, fix the links, they are screwed up because of the typedefs, there is some way around it
+ * but hey. */
+/**
+ * 
+ * The super class for al VisUIWidgets. All the typical VisUIWidgets
+ * derive from this. VisUIWidget is used as an intermediate user interface
+ * description. Mainly to set up configuration dialogs for plugins that
+ * are not widget set dependant.
+ *
+ * The VisUIWidget class hierarchy looks like following:
+ * - \a _VisUIWidget
+ *	- \a VisUILabel
+ *	- \a VisUIImage
+ *	- \a VisUIContainer
+ *		- \a VisUIBox
+ *		- \a VisUITable
+ *		- \a VisUIFrame
+ *	- \a VisUIMutator
+ *		- \a VisUIText
+ *		- \a VisUIColor
+ *		- \a VisUIRange
+ *			- \a VisUISlider
+ *			- \a VisUINumeric
+ *		- \a VisUIChoice
+ *			- \a VisUIPopup
+ *			- \a VisUIList
+ *			- \a VisUIRadio
+ *			- \a VisUICheckbox
+ */
+struct _VisUIWidget {
+	VisObject		 object;	/**< The VisObject data. */
+
+	VisUIWidget		*parent;	/**< Parent in which this VisUIWidget is packed.
+						 * This is possibly NULL. */
+	
+	VisUIWidgetType		 type;		/**< Type of VisUIWidget. */
+
+	const char		*tooltip;	/**< Optional tooltip text, this can be used to
+						 * give the user some extra explanation about the
+						 * user interface. */
+
+	int			 width;		/**< When size requisition is used, the width value will
+						 * be stored in this. */
+	int			 height;	/**< When size requisition is used. the height value will
+						 * be stored in this. When size requisition is not being
+						 * done both width and height will contain of -1. */
+};
+
+/**
+ * The VisUIContainer is a VisUIWidget that is used to pack other widgets in.
+ * A basic container can contain just one VisUIWidget, however when VisUIBox or
+ * VisUITable is used, it's possible to add more elements.
+ */
+struct _VisUIContainer {
+	VisUIWidget		 widget;	/**< The VisUIWidget data. */
+
+	VisUIWidget		*child;		/**< Pointer to the child VisUIWidget that is packed in this VisUIContainer. */
+};
+
+/**
+ * The VisUIBox inherents from VisUIContainer, but is capable to contain more childeren.
+ * The VisUIBox is used as a box of VisUIWidgets, packed vertical or horizontal.
+ */
+struct _VisUIBox {
+	VisUIContainer		 container;	/**< The VisUIContainer data. */
+
+	VisUIOrientType		 orient;	/**< Orientation, whatever the box packs the item in a vertical
+						 * order or in a horizontal order. */
+
+	VisList			 childs;	/**< A list of all child VisUIWidgets. */
+};
+
+/**
+ * VisUITableEntry is an entry in a VisUITable. the VisUITableEntry is not a VisUIWidget on
+ * itself. Instead it rembers the cell in which a VisUIWidget is placed in VisUITable and
+ * also has a reference to the VisUIWidget.
+ */
+struct _VisUITableEntry {
+	VisObject		object;		/**< The VisObject data. */
+
+	int			row;		/**< Row to which the VisUITableEntry is associated. */
+	int			col;		/**< Column to which the VisUITableEntry is associated. */
+
+	VisUIWidget		*widget;	/**< The VisUIWidget that is connected to this entry in the VisUITable. */
+};
+
+/**
+ * The VisUITable inherents from VisUIContainer, but is capable of placing VisUIWidgets in an aligned grid.
+ */
+struct _VisUITable {
+	VisUIContainer		 container;	/**< The VisUIContainer data. */
+
+	int			 rows;		/**< The number of rows in this VisUITable. */
+	int			 cols;		/**< The number of columns in this VisUITable. */
+
+	VisList			 childs;	/**< A list of all VisUITableEntry items that are related to
+						 * this table. */
+};
+
+/**
+ * The VisUIFrame inherents from VisUIContainer, it's used to put a frame with a label around a VisUIWidget.
+ */
+struct _VisUIFrame {
+	VisUIContainer		 container;	/**< The VisUIContainer data. */
+
+	const char		*name;		/**< The frame label text. */
+};
+
+/**
+ * The VisUILabel inherents from a VisUIWidget, it's used to as a label item in the user interface.
+ */
+struct _VisUILabel {
+	VisUIWidget		 widget;	/**< The VisUIWidget data. */
+
+	const char		*text;		/**< The label text. */
+	int			 bold;		/**< Whatever the label is being printed in bold or not. */
+};
+
+/**
+ * The VisUIImage inherents from a VisUIWidget, it's used to display a VisVideo within the user interface. For
+ * example it can be used to show a picture.
+ */
+struct _VisUIImage {
+	VisUIWidget		 widget;	/**< The VisUIWidget data. */
+
+	VisVideo		*image;		/**< The VisUIImage containing the image data. */
+};
+
+/**
+ * The VisUISeparator inherents from a VisUIWidget, it's used to display a separator between different user interface
+ * elements.
+ */
+struct _VisUISeparator {
+	VisUIWidget		 widget;	/**< The VisUIWidget data. */
+
+	VisUIOrientType		 orient;	/**< The orientation, whatever the separator is drawn in vertical
+						 * or horizontal style. */
+};
+
+/**
+ * The VisUIMutator inherents from a VisUIWidget, it's used as a super class for different type of mutator VisUIWidgets.
+ * Mutator VisUIWidgets are used to change a value in a VisParamEntry.
+ */
+struct _VisUIMutator {
+	VisUIWidget		 widget;	/**< The VisUIWidget data. */
+
+	VisParamEntry		*param;		/**< The VisParamEntry parameter that is associated with this
+						 * VisUIMutator. */
+};
+
+/**
+ * The VisUIRange inherents from a VisUIMutator, it's a type of mutator widget that focus on numeric input and
+ * numeric adjustment within a range.
+ */
+struct _VisUIRange {
+	VisUIMutator		 mutator;	/**< The VisUIMutator data. */
+
+	double			 min;		/**< The minimal value. */
+	double			 max;		/**< The maximal value. */
+	double			 step;		/**< Increase / decrease steps. */
+
+	int			 precision;	/**< Precision, in the fashion of how many numbers behind
+						 * the point. */
+};
+
+/**
+ * The VisUIEntry inherents from a VisUIMutator, it's used as a way to input text.
+ */
+struct _VisUIEntry {
+	VisUIMutator		 mutator;	/**< The VisUIMutator data. */
+
+	int			 length;	/**< Maximal length for the text. */
+};
+
+/**
+ * The VisUISlider inherents from a VisUIRange, it's used to display a slider which can be used
+ * to adjust a numeric value.
+ */
+struct _VisUISlider {
+	VisUIRange		 range;		/**< The VisUIRange data. */
+
+	int			 showvalue;	/**< Don't show just the slider, but also the  value it
+						 * represents at it's current position. */
+};
+
+/**
+ * The VisUINumeric inherents from a VisUIRange, it's used to display a numeric spin button that
+ * can be used to adjust a numeric value. A numeric spin button contains out of a small text field
+ * displaying the actual value, followed by two buttons which are used to increase or decrease the value.
+ *
+ * In most VisUI native implementations it's also possible to adjust the text field directly using
+ * the keyboard.
+ */
+struct _VisUINumeric {
+	VisUIRange		 range;		/**< The VisUIRange data. */
+};
+
+/**
+ * The VisUIColor inherents from a VisUIMutator, it's used to adjust the color that is encapsulated by
+ * a VisParamEntry.
+ */
+struct _VisUIColor {
+	VisUIMutator		 mutator;	/**< The VisUIMutator data. */
+};
+
+/**
+ * The VisUIChoiceList is not a VisUIWidget, but it's used by the different types of VisUIChoice widgets to
+ * store information about choices.
+ */
+struct _VisUIChoiceList {
+	VisObject		 object;	/**< The VisObject data. */
+
+	int			 count;		/**< The amount of choices that are present. */
+	VisList			 choices;	/**< A list of VisUIChoiceEntry elements. */ 
+};
+
+/**
+ * The VisUIChoiceEntry is not a VisUIWidget, but it's used by the different types of VisUIChoice widgets to
+ * store information regarding a choice within a VisUIChoiceList.
+ */
+struct _VisUIChoiceEntry {
+	VisObject		 object;	/**< The VisObject data. */
+
+	const char		*name;		/**< Name of this VisChoiceEntry. */
+	
+	VisParamEntry		*value;		/**< Link to the VisParamEntry that contains the value
+						 * for this VisChoiceEntry. */
+};
+
+/**
+ * The VisUIChoice inherents from a VisUIMutator, it's used as a super class for the different types of
+ * VisUIChoice VisUIWidgets.
+ */
+struct _VisUIChoice {
+	VisUIMutator		 mutator;	/**< The VisUIMutator data. */
+
+	VisParamEntry		*param;		/**< Pointer to the VisParamEntry that is the target to
+						 * contain the actual value. */
+
+	VisUIChoiceList		 choices;	/**< The different choices present. */
+};
+
+/**
+ * The VisUIPopup inherents from a VisUIChoice, it's used to represent choices in a popup fashion, where you
+ * can select an item.
+ */
+struct _VisUIPopup {
+	VisUIChoice		 choice;	/**< The VisUIChoice data. */
+};
+
+/**
+ * The VisUIList inherents from a VisUIChoice, it's used to represent choices in a list fashion.
+ */
+struct _VisUIList {
+	VisUIChoice		 choice;	/**< The VisUIChoice data. */
+};
+
+/**
+ * The VisUIRadio inherents from a VisUIChoice, it's used to represent choices in the fashion of radio buttons. These
+ * are a grouped type of checkboxes where only one item can be active at once.
+ */
+struct _VisUIRadio {
+	VisUIChoice		 choice;	/**< The VisUIChoice data. */
+
+	VisUIOrientType		 orient;	/**< Orientation of how the different radio buttons in the VisUIRadio button
+						 * group is ordered. */
+};
+
+/**
+ * The VisUICheckbox inherents from a VisUIChoice, it's used to represent one single checkbox widget. For this reason it
+ * can only represent two choices. One for the toggled state and one for the untoggled state.
+ */
+struct _VisUICheckbox {
+	VisUIChoice		 choice;	/**< The VisUIChoice data. */
+
+	const char		*name;		/**< Optional text behind the textbox. */
+};
+
+/* prototypes */
+VisUIWidget *visual_ui_widget_new (void);
+int visual_ui_widget_set_size_request (VisUIWidget *widget, int width, int height);
+int visual_ui_widget_set_tooltip (VisUIWidget *widget, const char *tooltip);
+const char *visual_ui_widget_get_tooltip (VisUIWidget *widget);
+VisUIWidget *visual_ui_widget_get_top (VisUIWidget *widget);
+VisUIWidget *visual_ui_widget_get_parent (VisUIWidget *widget);
+VisUIWidgetType visual_ui_widget_get_type (VisUIWidget *widget);
+
+int visual_ui_container_add (VisUIContainer *container, VisUIWidget *widget);
+VisUIWidget *visual_ui_container_get_child (VisUIContainer *container);
+
+VisUIWidget *visual_ui_box_new (VisUIOrientType orient);
+int visual_ui_box_pack (VisUIBox *box, VisUIWidget *widget);
+VisList *visual_ui_box_get_childs (VisUIBox *box);
+VisUIOrientType visual_ui_box_get_orient (VisUIBox *box);
+
+VisUIWidget *visual_ui_table_new (int rows, int cols);
+VisUITableEntry *visual_ui_table_entry_new (VisUIWidget *widget, int row, int col);
+int visual_ui_table_attach (VisUITable *table, VisUIWidget *widget, int row, int col);
+VisList *visual_ui_table_get_childs (VisUITable *table);
+
+VisUIWidget *visual_ui_frame_new (const char *name);
+
+VisUIWidget *visual_ui_label_new (const char *text, int bold);
+int visual_ui_label_set_text (VisUILabel *label, const char *text);
+int visual_ui_label_set_bold (VisUILabel *label, int bold);
+const char *visual_ui_label_get_text (VisUILabel *label);
+
+VisUIWidget *visual_ui_image_new (VisVideo *video);
+int visual_ui_image_set_video (VisUIImage *image, VisVideo *video);
+VisVideo *visual_ui_image_get_video (VisUIImage *image);
+
+VisUIWidget *visual_ui_separator_new (VisUIOrientType orient);
+VisUIOrientType visual_ui_separator_get_orient (VisUISeparator *separator);
+
+int visual_ui_mutator_set_param (VisUIMutator *mutator, VisParamEntry *param);
+VisParamEntry *visual_ui_mutator_get_param (VisUIMutator *mutator);
+
+int visual_ui_range_set_properties (VisUIRange *range, double min, double max, double step, int precision);
+int visual_ui_range_set_max (VisUIRange *range, double max);
+int visual_ui_range_set_min (VisUIRange *range, double min);
+int visual_ui_range_set_step (VisUIRange *range, double step);
+int visual_ui_range_set_precision (VisUIRange *range, int precision);
+
+VisUIWidget *visual_ui_entry_new (void);
+int visual_ui_entry_set_length (VisUIEntry *entry, int length);
+
+VisUIWidget *visual_ui_slider_new (int showvalue);
+
+VisUIWidget *visual_ui_numeric_new (void);
+
+VisUIWidget *visual_ui_color_new (void);
+
+VisUIChoiceEntry *visual_ui_choice_entry_new (const char *name, VisParamEntry *value);
+int visual_ui_choice_add (VisUIChoice *choice, const char *name, VisParamEntry *value);
+int visual_ui_choice_add_many (VisUIChoice *choice, VisParamEntry *paramchoices);
+int visual_ui_choice_free_choices (VisUIChoice *choice);
+int visual_ui_choice_set_active (VisUIChoice *choice, int index);
+int visual_ui_choice_get_active (VisUIChoice *choice);
+VisUIChoiceEntry *visual_ui_choice_get_choice (VisUIChoice *choice, int index);
+VisUIChoiceList *visual_ui_choice_get_choices (VisUIChoice *choice);
+
+/* FIXME look at lists with multiple selections... */
+
+VisUIWidget *visual_ui_popup_new (void);
+
+VisUIWidget *visual_ui_list_new (void);
+
+VisUIWidget *visual_ui_radio_new (VisUIOrientType orient);
+
+VisUIWidget *visual_ui_checkbox_new (const char *name, int boolcheck);
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* _LV_UI_H */