Jan 2001, S.Geerken@ping.de Last update: Dec 2004 ======== DwWidget ======== The base object for all Dw widgets. Structures ========== DwRectangle ----------- A replacement for GdkRectangle, the only difference is the use of 32 instead of 16 bit integers. DwAllocation, DwRequisition --------------------------- Similar to GtkAllocation and GtkRequisition. Instead of a height, you have two members, ascent and descent. DwExtremes ---------- A structure containing the minimal and maximal width of a widget. See get_extremes below for details. DwWidget -------- Some members you may use: parent The parent widget. NULL for toplevel widgets. flags See below. style The style attached to the widget, this must always be defined, but is not created automatically. Instead, this has to be done immediately after creating the widget (e.g., in a_Web_dispatch_by_type). This style contains attributes and resources for general drawing. See DwStyle.txt for details. These members should only be used within the "core" (GtkDw*, DwWidget and DwEmbedGtk): viewport The viewport containing the widget. Defined for all widgets. allocation, requisition, extremes, user_requisition These are used to optimize several wrappers, see below. anchors_table See notes on achors. Flags ----- Flags can be set and unset with DW_WIDGET_SET_FLAGS and DW_WIDGET_UNSET_FLAGS. For reading flags use the macros DW_WIDGET_... DW_NEEDS_RESIZE DW_EXTREMES_CHANGED Denotes that the widget must be resized. Used only internally. See Dw.txt and the source for more details. DW_NEEDS_ALLOCATE Set to overide the optimation in a_Dw_widget_size_allocate. Used only internally. DW_REALIZED Set when the widget is realized. Should be used to prevent crashes in certain situations. Following flags describe characteristics of widgets and are typically set in the init function: DW_USES_HINTS A widget with this flag set has a complex way to deal with sizes, and should - implement the functions set_width, set_ascent, set_descent, and get_extremes, and - deal completely with width and height in widget->style. Examples are DwPage and DwTable. Other widgets, like DwImage and DwHRuler, are much simpler and don't have to set this flag. For these widgets, much of the size calculation is done by the parent widget. This flag is unset by default. DW_HAS_CONTENT If this flag is set, more space is reserved for the widget in some circumstances. E.g., if an image has a width of 100%, it makes sense to use more space within a table cell, as compared to a horizontal ruler, which does not "have a content". This flag is set by default. Signal Prototypes ================= - void size_request (DwWidget *widget, DwRequisition *requisition); Similar to Gtk. void get_extremes (DwWidget *widget, DwExtremes *extremes); Return the maximal and minimal width of the widget, equivalent to the requisition width after calling set_width with zero and infinitive, respectively. This is important for fast table rendering. Simple widgets do not have to implement this; the default is the requisition width for both values. - void size_allocate (DwWidget *widget, DwAllocation *allocation); Similar in Gtk. Note: allocation has world coordinates. - void set_width (DwWidget *widget, guint32 width); - void set_height (DwWidget *widget, guint32 height); These are hints by the caller, which *may* influence the size returned by size_request. The implementation should call Dw_widget_queue_resize if necessary. In most cases, these signals do not have to be implemented. Currently, only the DwPage widget uses this to determine the width for rewrapping text (note that the resulting width returned by Dw_page_size_request may be _bigger_) and relative sizes of the children. - void draw (DwWidget *widget, DwRectangle *area, GdkEventExpose *event); Draw the widget's content in the specified area. It may either be caused by an expose event, or by an internal drawing request (e.g., followed by resizing of widgets). In the first case, you get the *original* expose event as third argument. In the latter, event is NULL. The area argument has widget coordinates. A DwContainer is responsible for drawing its children. (Since DwWidget's are always windowless, there was no need for two signals, "draw" and "expose_event".) - void realize (DwWidget *widget); Create all necessary X resources. Called when either the viewport (top-level widgets) or, respectively, the parent Dw widget is realized, or an widget is added to an already realized Dw widget/viewport. - void unrealize (DwWidget *widget); Remove created X resources. - gint button_press_event (DwWidget *widget, guint32 x, guint32 y, GdkEventButton *event); This signal is emitted when the user presses a mouse button in a DwWidget. x and y are the coordinates relative to the origin of the widget, event is the *original* event, which may, e.g., be used to determine the number of the pressed button, the state of the shift keys, etc. The implementation of this signal should return TRUE, if the event has been processed, otherwise FALSE. A DwContainer is *not* responsible for delivering button press events to its children. Instead, Dw first emits the button_press_event signal for the most inner widgets and continues this for the parents, until TRUE is returned. - gint button_release_event (DwWidget *widget, guint32 x, guint32 y, GdkEventButton *event); Compare button_press_event. - gint motion_notify_event (DwWidget *widget, guint32 x, guint32 y, GdkEventMotion *event); Compare button_press_event. event may be NULL when the call was caused by something different than a "real" motion notify event. E.g., either when widgets are moved (not yet implemented), or the viewport. - gint enter_notify_event (DwWidget *widget, DwWidget *last_widget, GdkEventMotion *event); These "events" are simulated based on motion nofify events. event is the *original* event (may also be NULL in some cases). last_widget is the widget in which the pointer was in before. - gint leave_notify_event (DwWidget *widget, DwWidget *next_widget, GdkEventMotion *event); Compare enter_notify_event. next_widget is the widget the pointer is now in. Useful Internal Functions and Macros ==================================== - gint Dw_widget_intersect (DwWidget *widget, DwRectangle *area, DwRectangle *intersection); Calculates the intersection of widget->allocation and area, returned in intersection (in widget coordinates!). Typically used by containers when drawing their children. Returns whether intersection is not empty. - gint32 Dw_widget_x_viewport_to_world (DwWidget *widget, gint16 viewport_x); - gint32 Dw_widget_y_viewport_to_world (DwWidget *widget, gint16 viewport_y); - gint16 Dw_widget_x_world_to_viewport (DwWidget *widget, gint32 world_x); - gint16 Dw_widget_y_world_to_viewport (DwWidget *widget, gint32 world_y); These functions convert between world and viewport coordinates. - void Dw_widget_queue_draw (DwWidget *widget); - void Dw_widget_queue_draw_area (DwWidget *widget, gint32 x, gint32 y, guint32 width, guint32 height); - void Dw_widget_queue_clear (DwWidget *widget); - void Dw_widget_queue_clear_area (DwWidget *widget, gint32 x, gint32 y, guint32 width, guint32 height); Equivalents to the Gtk+ functions. They (currently) result in a call of gtk_widget_xxx_area with the viewport as first argument. x and y are widget coordinates. - void Dw_widget_queue_resize (DwWidget *widget, gint ref, gboolean extremes_changed); Similar to gtk_widget_queue_resize. Call this function when the widget has changed its size. The next call to Dw_xxx_size_request should then return the new size. See Dw.txt for explanation on how to use the ref argument, extremes_changed specifies whether the extremes have changed (the latter is often not the case for an implementations of set_{width|ascent|descent}). - void Dw_widget_set_anchor (DwWidget *widget, gchar *name, int pos); Add an anchor to a widget. The name will not be copied, it has to be stored elsewhere (DwPage e.g. stores it in the DwPageWord structure). - void a_Dw_widget_set_cursor (DwWidget *widget, GdkCursor *cursor) Set the cursor for a DwWidget. cursor has to be stored elsewhere, it is not copied (and not destroyed). If cursor is NULL, the cursor of the parent widget is used. (This will probably be changed in the future and replaced by a common style mechanism.) - DW_WIDGET_WINDOW (widget) Returns the window a widget should draw into. External Functions ================== - void a_Dw_widget_set_usize (DwWidget *widget, guint32 width, guint32 ascent, guint32 descent); Override the "desired" size of a widget. Further calls of a_Dw_widget_request_size will return these values, except those specified as -1. A possible use shows Html_add_widget in html.c. (This will probably be removed. Instead DwStyle should be used.) - void a_Dw_widget_set_bg_color (DwWidget *widget, gint32 color); Set the background color of a widget. This works currently only for the top-level widget. In this case, the background color of the GtkDwViewport is changed. In future, background colors for all widgets will be needed, e.g., for table cells (will be DwPage's), this will (probably) be based on filled rectangles. - void a_Dw_widget_scroll_to (DwWidget *widget, int pos) Scroll viewport to pos (vertical widget coordinate). There are furthermore wrappers for the signals, in some cases they are optimized and/or provide further functionality. In (almost) no case should you emit the signals directly. See dw_widget.c for more details.