EZ_ConfigureWidget


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)