NAME
EZ_ConfigureWidget - configure an existing widget
SYNOPSIS
#include <EZ.h>
void EZ_ConfigureWidget(EZ_Widget *widget", ... )
ARGUMENTS
widget Specifies a widget
... Specify configuration options and their values.
DESCRIPTION
EZ_ConfigureWidget sets or modifies widget attributes,
things like label string, color, border. This function
takes a variable length arguments, 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. For
example
EZ_ConfigureWidget(slider,
EZ_SLIDER_RANGE, -10.0, 20.0,
EZ_SLIDER_DISPLAY_VALUE, True,
EZ_SLIDER_RESOLUTION, 0.5
EZ_SLIDER_INIT_VALUE, 10.0,
0);
sets the range of slider to [-10.0, 20.0]; sets the current slider
value to 10.0; set the slider resolution to 0.5 and enable the slider
to display its current value.
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 width hint of a widget.
EZ_HEIGHT_HINT, int_h
Specifies the height hint of a 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, EZ_BORDER_SUNKEN,
EZ_BORDER_EMBOSSED or EZ_BORDER_ENGRAVED.
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 hori-
zontally between children widgets.
EZ_IPADY, int_ipy
Specifies the amount of spaces to be inserted verti-
cally between children widgets.
EZ_ORIENTATION, int_ori
Specifies the orientation of a container wid-
get(except row-column widget). int_ori must be one
of EZ_HORIZONTAL, EZ_HORIZONTAL_LEFT,EZ_HORIZON-
TAL_RIGHT, EZ_HORIZONTAL_CENTER, EZ_VERTICAL,EZ_VER-
TICAL_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_HORI-
ZONTALLY, EZ_FILL_VERTICALLY or EZ_FILL_BOTH.
EZ_PROPAGATE, int_tf
Specifies whether or not change of geometry of a wid-
get 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_CURSOR, Cursor_cur
Specifies a cursor for widget. The specified cursor
will be displayed when the mouse pointer enters the
widget window. The option value must be the return
value of EZ_GetCursor or EZ_CreateCursor*** or one of
the Xlib's cursor creation routines.
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 wid-
get. 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_TRAN-
SIENT_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 mov-
able 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_INDI-
CATOR, EZ_SQUARE_INDICATOR, EZ_SUNKEN_SQUARE_INDICA-
TOR, EZ_DIAMOND_INDICATOR, EZ_SUNKEN_DIAMOND_INDICA-
TOR, 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 wid-
get window.
EZ_DND_DRAG_CURSOR, Cursor_cur
Specifies an X cursor for drag and drop. The speci-
fied cursor will replace the default cursor when the
widget is being draged. The option value must be the
return value of EZ_GetCursor or EZ_CreateCursor*** or
one of the Xlib's cursor creation routines.
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 scroll-
bar 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 wid-
get. There are two selection modes, a row mode (rep-
resented 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 wid-
get.
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_CLASS, str_name
Specifies a class name for a widget.
EZ_POPUP_NAME, str_name
This option only applies to OptionalEntry and FileSe-
lector. It specifies an instance name for the popup
listbox on tese widgets.
EZ_LABELED_ICON, int_mode
This option only applies to FreeLabel/Icon widget.
It specifies whether or not the textual label be dis-
played beneath the pixmap label (if any). There are
three modes, 0, 1 and 2,
EZ_GRID_CELL_GEOMETRY, int_x,int_y,int_w,int_h
Specify the geometry of a cell in a row-column wid-
get. 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_VERTI-
CALLY or EZ_FILL_BOTH. This option is used to dis-
tribute 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 mini-
mal 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.
EZ_LCD_NDIGITS, int_nd
Specifies the width (number of digits) of an LCD wid-
get.
EZ_LCD_FONT_SIZE, int_size
Specifies the font width for an LCD widget.
EZ_LCD_BACKGROUND, string_color
Specifies a background color for an LCD widget.
EZ_LCD_GOREGROUND, string_color
Specifies a foreground color for an LCD widget.
EZ_LED_BACKGROUND, string_color
Specifies a background color for an LED widget.
EZ_LED_PIXEL_COLOR, string_color
Specifies a color for the off diodes of an LED wid-
get.
EZ_LED_WIDTH, int_w
Specifies the width of an LED widget, in "LED pix-
els".
EZ_LED_HEIGHT, int_h
Specifies the height of an LED widget, in "LED pix-
els".
EZ_LED_PIXEL_SIZE, int_size
Specifies the size of a "LED pixel" of an LED widget.
int_size must be an integer between 1 and 4 inclu-
sive.
EZ_LED_COLOR_FUNCTION, unsigned_long_F_arg_int_int
Specifies a function to choose the colors for on
diodes on an LED widget.
EZ_WMHINTS, int_hints
Specifies a set of window manager hints. int_hints is
or'ed from PMinSize, PMaxSize, PAspect and PWinGrav-
ity. This option is applicable only to toplevel wid-
gets. If PMinSize is set, the current minimal size
or in the case the geometry is not yet computed, the
first known minimal size of the widget will be taken
as the minimal size of the widget. If PMaxSize is
set, the current size or the first known size of the
widget will be taken as the maximal size of the wid-
get.
EZ_WM_WINDOW_NAME, str_name
Specifies the window name. Available only for
toplevel widgets.
EZ_WM_INITIAL_STATE, int_state
Sets the window manager hints 'initial_state' for
toplevel widgets. Possible values are: 'IconicState'
and 'NormalState'. The default value is 'Normal-
State'.
EZ_WM_ICON_NAME, str_name
Sets the window manager hints 'icon_name' for
toplevel widgets.
EZ_WM_ICON_XPM_FILE, str_name
Sets the window manager 'icon_window' hint. Value is
a XPM file name.
EZ_WM_ICON_PIXMAP, label_pixmap
Sets the window manager 'icon_window' hint. Value is
of type EZ_LabelPixmap, must be create by one of
EZ_CreateLabelPixmapFrom...
EZ_WM_ICON_LOCATION_HINT, int_x, int_y
EZ_WM_LOCATION_HINT, int_x, int_y
EZ_WM_SIZE_HINT, int_w, int_h
EZ_WM_MAX_SIZE_HINT, int_w, int_h
EZ_WM_MIN_SIZE_HINT, int_w, int_h
These options set the corresponding window manager
hints.
EZ_HSCROLL_INCREMENT, int_unit
Specifies the discrete increment for a horizontal
scrollbar or the horizontal scrollbar associated with
a composite widget.
EZ_VSCROLL_INCREMENT, int_unit
Specifies the discrete increment for a vertical
scrollbar or the vertical scrollbar associated with a
composite widget.
EZ_SMETER_VALUE, float_value
Specifies the the current value of the first quantity
displayed on a status meter.
EZ_SMETER_RANGE, float_from, float_to
Specifies the the TOTAL range of a status meter.
EZ_SMETER_STOPED, int_status
Specifies whether or not to stop a status meter.
Option value is either True or False.
EZ_SMETER_BACKGROUND, str_color
Specifies the background color of a status meter.
EZ_SMETER_FOREGROUND, str_color
Specifies the foreground color of a status meter.
EZ_SMETER_SHOW_VALUE, int_trueOrFalse
Specifies the whether or not the percent value should
be displayed on a status meter.
EZ_SMETER_ORIENTATION, int_orien
Specifies an orientation for a status meter, either
EZ_HORIZONTAL or EZ_VERTICAL
EZ_SMETER_FOREGROUND_N, int_idx, str_color
Specifies a color to be used to display the idx th
quantity. idx is an integer between 0 and 4 inclu-
sive.
EZ_SMETER_VALUE_N, int_idx, float_value
Specifies the value of the idx th quantity. idx is
an integer between 0 and 4 inclusive.
EZ_SMETER_RANGE_N, int_idx, float_from, float_to
Specifies the range of the idx th quantity. idx is
an integer between 0 and 4 inclusive.
EZ_SMETER_STYLE, int_width, int_sep
This option specifies the parameters used to display
the status bar. It takes two integers, the width of
individual bars and the space between neighboring
bars.
EZ_FORGET_X, int_TrueOrFalse
EZ_FORGET_Y, int_TrueOrFalse
EZ_FORGET_POSITION, int_TrueOrFalse
EZ_FORGET_W, int_TrueOrFalse
EZ_FORGET_H, int_TrueOrFalse
EZ_FORGET_SIZE, int_TrueOrFalse
EZ_FORGET_GEOMETRY, int_TrueOrFalse
These options, if set true, tells EZWGL to forget the
configured attributes (position or dimension) after
the corresponding widget is displayed. They are use-
ful if you want your widget start up with certain
geometry and want it to be resizable.
EZ_MARK_CLEAN, int_TrueOrFalse
Whenever EZ_ConfigureWidget is invoked, the corre-
sponding widget will be redisplayed. This option
tells EZ_ConfigureWidget not to update the display.
It is not an attribute of widgets, but rather acts
like an argument to EZ_ConfigureWidget.
SEE ALSO
EZ_CreateWidget(3), EZ_DisplayWidget(3), EZ_DestroyWidget(3)