Initial revision

1 files changed, 339 insertions, 0 deletions

diff --git a/doc/DwWidget.txt b/doc/DwWidget.txt
new file mode 100644
index 00000000..fed0a3be
--- /dev/null
+++ b/doc/DwWidget.txt
@@ -0,0 +1,339 @@
+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.