EZ_CreateWidget(3)

NAME
EZ_CreateWidget - create an EZ widget

SYNOPSIS
#include <EZ.h>

EZ_Widget *EZ_CreateWidget(int type, EZ_Widget *parent, ...)

ARGUMENTS
type Specifies a symbolic widget type (see below).

parent Specifies the parent widget or NULL.

... Specifies configuration options, a list of symbols each followed by one or more values. The last symbol must be NULL, which is itself not followed by any values.

DESCRIPTION

EZ_CreateWidget creates a widget and initializes the widget using the specified configuration options. For example

   extern void exit();
   EZ_Widget *button;
                           /* type                   parent */
   button = EZ_CreateWidget(EZ_WIDGET_NORMAL_BUTTON, NULL,
                            /* option,       option value(s) */
                            EZ_LABEL_STRING, "Hello World",
                            EZ_UNDERLINE,    0,
                            EZ_CALLBACK,     exit, NULL,
                            0);

creates a push button widget labeled by "Hello World" with
the letter 'H' underlined.

SYMBOLIC WIDGET TYPES

EZ_WIDGET_FRAME,                  EZ_WIDGET_NORMAL_BUTTON,
EZ_WIDGET_CHECK_BUTTON,            EZ_WIDGET_RADIO_BUTTON,
EZ_WIDGET_MENU_BUTTON,           EZ_WIDGET_MENU_SEPARATOR,
EZ_WIDGET_LABEL,                    EZ_WIDGET_RAW_XWINDOW,
EZ_WIDGET_MENU_SUBMENU,      EZ_WIDGET_MENU_NORMAL_BUTTON,
EZ_WIDGET_MENU_CHECK_BUTTON,  EZ_WIDGET_MENU_RADIO_BUTTON,
EZ_WIDGET_VERTICAL_SLIDER,    EZ_WIDGET_HORIZONTAL_SLIDER,
EZ_WIDGET_ENTRY,             EZ_WIDGET_VERTICAL_SCROLLBAR,
EZ_WIDGET_HORIZONTAL_SCROLLBAR,        EZ_WIDGET_LIST_BOX,
EZ_WIDGET_TEXT,                       EZ_WIDGET_NOTE_BOOK,
EZ_WIDGET_PANE_HANDLE,                 EZ_WIDGET_EXECUTOR,
EZ_WIDGET_OPTIONAL_ENTRY,         EZ_WIDGET_FILE_SELECTOR,
EZ_WIDGET_TREE,                       EZ_WIDGET_LIST_TREE,
EZ_WIDGET_FANCY_LIST_BOX,             EZ_WIDGET_WORK_AREA,
EZ_WIDGET_ROW_COLUMN,                      EZ_WIDGET_ICON,
EZ_WIDGET_FREE_LABEL,                 EZ_WIDGET_3D_CANVAS,
EZ_WIDGET_NB_PAGE,                     EZ_WIDGET_NW_LABEL

CONFIGURATION SYMBOLS AND THEIR VALUES
The set of widget configuration options and their values are listed below. For each option value, the string before the last _ is its type.

EZ_X, int_x
Specifies the x coordinate of the upper-left corner of the widget window in its parent window.

EZ_Y, int_y
Specifies the y coordinate of the upper-left corner of the widget window in its parent window.

EZ_WIDTH, int_w
Specifies the width of a widget.

EZ_HEIGHT, int_h
Specifies the height of a widget.

EZ_WIDTH_HINT, int_w
Specifies the suggested width of a widget.

EZ_HEIGHT_HINT, int_h
Specifies the suggested height of widget.

EZ_BORDER_WIDTH, int_bw
Specifies a border width.

EZ_BORDER_TYPE, int_bt
Specifies a border type. int_bt must be one of EZ_BORDER_NONE, EZ_BORDER_FLAT, EZ_BORDER_RIDGE, EZ_BORDER_GROOVE, EZ_BORDER_RAISED or EZ_BORDER_SUNKEN.

EZ_PADX, int_px
Specifies the horizontal padding between the widget border and its contents.

EZ_PADY, int_py
Specifies the vertical padding between the widget border and its contents.

EZ_IPADX, int_ipx
Specifies the amount of spaces to be inserted horizontally between children widgets.

EZ_IPADY, int_ipy
Specifies the amount of spaces to be inserted vertically between children widgets.

EZ_ORIENTATION, int_ori
Specifies the orientation of a container widget(except row-column widget). int_ori must be one of EZ_HORIZONTAL, EZ_HORIZONTAL_LEFT,EZ_HORIZONTAL_RIGHT, EZ_HORIZONTAL_CENTER, EZ_VERTICAL,EZ_VERTICAL_TOP, EZ_VERTICAL_BOTTOM or EZ_VERTICAL_CENTER.

EZ_SIDE, int_sd
Specifies a way to align children widgets. int_sd must be one of EZ_CENTER, EZ_LEFT, EZ_RIGHT, EZ_TOP or EZ_BOTTOM.

EZ_LABEL_POSITION, int_lp
Specifies a location to anchor a label. int_lp must be one of EZ_CENTER, EZ_LEFT, EZ_RIGHT, EZ_TOP, EZ_BOTTOM, EZ_TOP_LEFT, EZ_TOP_RIGHT, EZ_BOTTOM_LEFT or EZ_BOTTOM_RIGHT.

EZ_LABEL_JUSTIFICATION, int_jst
Specifies the justfication for textual labels. int_jst must be one of EZ_CENTER, EZ_LEFT or EZ_RIGHT.

EZ_FILL_MODE, int_fmode
Specifies a way to stretch children widgets. int_fmode must be one of EZ_FILL_NONE, EZ_FILL_HORIZONTALLY, EZ_FILL_VERTICALLY or EZ_FILL_BOTH.

EZ_PROPAGATE, int_tf
Specifies whether or not change of geometry of a widget be propagated to the whole widget tree.

EZ_CALLBACK, EZ_CallBack_cbk, voidptr_cdata
Specifies a callback procedure and a client data to be passed to the callback. Use this option only when a widget is to have only one callback.

EZ_FOREGROUND, str_fg
Specifies a forground color.

EZ_BACKGROUND, str_bg
Specifies a background color.

EZ_PIXMAP_FILE, str_file
Specifies an X bitmap file or a X pixmap file (an xpm image).

EZ_BITMAP_DATA, array_of_char,int_width,int_height
Specify an X bitmap.

EZ_PIXMAP_DATA, array_of_str
Specifies an XPM image data.

EZ_X_PIXMAP, Pixmap_p,int_x,int_y,int_width,int_height
Specify a regular region of a native X pixmap to used to label a widget.

EZ_LABEL_PIXMAP, EZ_Pixmap_p
Specifies an internal pixmap.

EZ_FONT_ID, int_id
Specifies a fond id.

EZ_FONT_NAME, str_name
Spcifies an X11 font name.

EZ_TEXT_LINE_LENGTH, int_len
Specifies the wrap around length for textual labels.

EZ_SLIDER_LENGTH, int_len
Specifies the length of the sliding button on a slider.

EZ_SLIDER_WIDTH, int_width
Specifies the width of the sliding button on a slider.

EZ_SLIDER_BORDER_WIDTH, int_bw
Specifies the border width of the sliding button on a slider.

EZ_SLIDER_RESOLUTION, float_re
Specifies the resolution of a slider.

EZ_SLIDER_RANGE, float_mn, float_mx
Specifies the range of a slider.

EZ_SLIDER_DISPLAY_VALUE, int_tf
Specifies whether or not to display the current value on a slider widget.

EZ_SLIDER_INIT_VALUE, float_v
Specifies the initial value on a slider.

EZ_INDICATOR_SIZE_ADJUST, int_a
Specifies an adjustment of the size of the indicator on a radiobutton or a checkbutton.

EZ_IMAGE_FILE, str_filename
Specifies an image file name. Supported image formats are: ppm, xpm, bmp, gif and jpeg.

EZ_BUTTON_SHORTCUT, str_ks
Specifies a keyboard shortcut for a button type widget. str_ks must be in the format C-key or M-key or Control-key or Meta-key.

EZ_EVENT_HANDLER, EZ_EventHandler_handler, ptr_data
Specifies an event handler and a client data to be passed to the event handler. Use this option only if a widget is to have only one private event handler.

EZ_LABEL_STRING, str_label
Specifies a textual label.

EZ_RESERVE_MENU_BUTTON, int_tf
Specifies whether or not Button3 should be reserved for posting popup menus for a 3D canvas widget.

EZ_BACKING_STORE, int_tf
Specifies whether or not to set the backing store attribute on the window of a widget.

EZ_EXPAND, int_tf
Specifies whether or not a widget be stretched in the direction opposite to its parent' orientation, to the corresponding size of its parent.

EZ_TRANSIENT, int_tf
Specifies whether or not to set the XA_WM_TRANSIENT_FOR window manager hint on a toplevel widget window.

EZ_SCROLLBAR_WIDTH, int_w
Specifies the width of the sliding button on a scrollbar widget.

EZ_SCROLLBAR_BORDER_WIDTH, int_bw
Specifies the border width of the sliding button on a scrollbar widget.

EZ_TEXT_SPACING, int_sp
Specifies the spacing between lines in a text widget.

EZ_UNDERLINE, int_idx
Specifies the index of the character to be underlined on a textual label. Underlined characters are used as keyboard shortcuts for button type widgets.

EZ_BUBBLE_HELP, str_help
Specifies a bubble help string.

EZ_FREELABEL_MOVABLE, int_tf
Specifies whether or not a freelabel widget be movable by Button1 press-drag-release.

EZ_INDICATOR_TYPE, int_type
Specifies an indicator type for a radiobutton or a checkbutton. int_type must be one of EZ_EMPTY_INDICATOR, EZ_SQUARE_INDICATOR, EZ_SUNKEN_SQUARE_INDICATOR, EZ_DIAMOND_INDICATOR, EZ_SUNKEN_DIAMOND_INDICATOR, EZ_CIRCLE_INDICATOR, EZ_CHECK_INDICATOR or EZ_RECTANGLE_INDICATOR.

EZ_INDICATOR_COLOR, str_clr
Specifies a highlight color for the indicator on a radiobutton or a checkbutton.

EZ_TEXT_BACKGROUND, str_clr
Specifies the background color for a text widget.

EZ_SELECTION_BACKGROUND, str_clr
Specifies the background color for the slection in text widget, entry, listbox, tree, fancy-listbox or work-area.

EZ_SELECTION_FOREGROUND, str_clr
Specifies the foreground color for the selected item(s) in a fancy-listbox, a tree or a work-area widget.

EZ_CLIENT_PTR_DATA, ptr_data
Specifies a generic pointer to be stored in a widget.

EZ_CLIENT_INT_DATA, int_data
Specifies an integer to be stored in a widget.

EZ_DESTROY_CALLBACK, EZ_CallBack_callback, ptr_data
Specify a destroy callback and a client data to be passed to the callback. Use this option if a widget is to have only one destroy callback.

EZ_IS_EMBEDER, int_tf
Specifies whether or not the widget should reparent other toplevel windows that lie entirely in its widget window.

EZ_DND_DRAG_CURSOR, Cursor_cur
Specifies an X cursor for drag and drop. The specified cursor will replace the default cursor when the widget is being draged.

EZ_DND_BUBBLE_HELP, str_hlp
Specifies a DND bubble help string. DND bubble will be displayed when a drag is paused over the widget window and the widget is a drop site.

EZ_SHAPED_WINDOW, int_tf
Specifies whether or not the shape mask in a image label should be used to reshape the widget window.

EZ_MOTION_CALLBACK, EZ_CallBack_callback, ptr_data
Specify a motion callback and a client data to be passed to the callback. Use this option if a widget is to have only one motion callback.

EZ_CHECK_BUTTON_ON_VALUE, int_v
Specifies the value corresponding to the on state of a check button.

EZ_CHECK_BUTTON_OFF_VALUE, int_v
Specifies the value corresponding to the off state of a check button.

EZ_CHECK_BUTTON_ON_OFF, int_tf
Specifies a state for a checkbutton. int_tf must be EZ_ON or EZ_OFF.

EZ_RADIO_BUTTON_GROUP, int_id
Specifies the group id for a radio button.

EZ_RADIO_BUTTON_VALUE, int_v
Specifies the value to set to the group variable when a radiobutton is checked.

EZ_OPTIONAL_HSCROLLBAR, int_tf
Specifies whether or not to create a horizontal scrollbar for a textwidget, a tree, a listbox, a fancy-listbox or a work-area.

EZ_OPTIONAL_VSCROLLBAR, int_tf
Specifies whether or not to create a vertocal scrollbar for a textwidget, a tree, a listbox, a fancy-listbox or a work-area.

EZ_FANCY_LIST_BOX_TYPE, int_type
Specifies the selection mode in a fancy-listbox widget. There are two selection modes, a row mode (represented by 1) and a item mode (represented by 0).

EZ_FANCY_LIST_BOX_COLUMNS, int_cln
Specifies the number of columns in a fancy-listbox widget.

EZ_GLOB_PATTERN, str_pattern
Specifies the initial glob pattern in a file-selector widget.

EZ_TEXT_WIDGET_EDITABLE, int_tf
Specifies whether editing is allowed in a text widget.

EZ_ENTRY_STRING, str_datr
Specifies a initial string for an entry widget.

EZ_RETURN_VALUE, int_v
Specifies the return value for a menu-item.

EZ_OPTIONAL_ENTRY_REMEMBER_HISTORY, int_tf
Specifies whether or not an optional-entry should remember its histroy.

EZ_OPTIONAL_ENTRY_EDITABLE, int_tf
Specifies whether or not editing is allowed an optional-entry widget.

EZ_MENU_TEAR_OFF, int_tf
Specifies whether or not to add a tear-off item (a dashed line) on a menu.

EZ_LOCATION, int_x, int_y
Specify the coordinates of the upper-left corner of a widget window relative to its parent's widget window.

EZ_SIZE, int_w, int_h
Specify the width and height of a widget.

EZ_GEOMETRY, int_x, int_y, int_w, int_h
Specify the location and dimension of a widget.

EZ_SIZE_HINT, int_w, int_h
Specify the suggested width and height of a widget.

EZ_HIGHLIGHT_PAD, int_hb
Specifies the amount of space to be inserted outside the border of a widget window. This extra space is used to draw keyboard focus highlight box around the widget.

EZ_NAME, str_name
Specifies a name for a widget.

EZ_GRID_CELL_GEOMETRY, int_x,int_y,int_w,int_h
Specify the geometry of a cell in a row-column widget. int_x,int_y specify the location of the cell and int_w,int_h specify the horizontal and vertical span of the cell.

EZ_GRID_CELL_PLACEMENT, int_fill, int_anchor
Specify the fill mode and anchor position for a cell in a row-column widget. int_fill must be one of EZ_FILL_NONE, EZ_FILL_HORIZONTALLY, EZ_FILL_VERTICALLY or EZ_FILL_BOTH. This option is used to distribute extra space of the cell to its occupant. int_anchor must be one of EZ_CENTER, EZ_LEFT, EZ_RIGHT, EZ_TOP, EZ_BOTTOM, EZ_TOP_LEFT, EZ_TOP_RIGHT, EZ_BOTTOM_LEFT or EZ_BOTTOM_RIGHT. This option is used to determine the anchor position for a cell occupant in case the cell is larger than the dimension of its occupant.

EZ_GRID_ROW_CONSTRAINS, int_idx, int_min, int_weight, int_pad
Specify the row constrains for a row in a row-column widget. int_idx is the index of the row to which the constrins will be set; int_min is the minimal height of the row; int_weight is the weight of the row, it is used to compute the extra space to be added/removed to the row when the row-column widget is resized; int_pad specifies the amount of extra space to be inserted at the top and the bottom of the row.

EZ_GRID_COLUMN_CONSTRAINS, int_idx, int_min, int_weight, int_pad
Specify the column constrains for a column in a row-column widget. int_idx is the index of the column to which the constrins will be set; int_min is the minimal width of the column; int_weight is the weight of the column, it is used to distribute the extra space to be added/removed to the column when the row-column widget is resized; int_pad specifies the amount of extra space to be inserted at the left and the right of the row.

EZ_GRID_CONSTRAINS, int_RorC, int_idx, int_min, int_weight, int_pad
Specify a row constrains or a column constrains. int_RorC must be one of EZ_ROW or EZ_COLUMN.

SEE ALSO
EZ_DisplayWidget(3), EZ_ConfigureWidget(3), EZ_DestroyWidget(3)