[Anygui-checkins] CVS: nondist/irfc irfc-0014.txt,1.4,1.5

[Magnus L. H. <ml...@us...>]

Update of /cvsroot/anygui/nondist/irfc
In directory usw-pr-cvs1:/tmp/cvs-serv12002

Modified Files:
	irfc-0014.txt 
Log Message:


Index: irfc-0014.txt
===================================================================
RCS file: /cvsroot/anygui/nondist/irfc/irfc-0014.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** irfc-0014.txt	9 Feb 2002 11:27:12 -0000	1.4
--- irfc-0014.txt	15 Feb 2002 21:55:05 -0000	1.5
***************
*** 31,36 ****
  
     For each Anygui component there are three main classes at work: (1)
!    The front-end proxy object, (2) the back-end proxy object, and (3)
!    the native widget.
  
     The front-end proxy presents the public interface to the
--- 31,36 ----
  
     For each Anygui component there are three main classes at work: (1)
!    The front-end proxy object, (2) the back-end wrapper object, and
!    (3) the native widget.
  
     The front-end proxy presents the public interface to the
***************
*** 40,128 ****
     The back-end wrapper presents a unified and simple interface for
     manipulating the native widget. This is done by the proxy object,
!    through accessors such as setText, or setParent. Note that there
!    are only setter methods -- the wrapper (and the native widget) are
!    considered stateless.
  
     The back-end wrapper installs event handlers so that it can send
!    the proper Anygui events as a reaction to native events, and so
!    that it can update the proxy state whenever the native widget is
!    modified by the user. This modification is done through the proxy's
!    modify method.
  
     The wrapper is responsible for creating and destroying the native
     widget as needed (for instance creating the widget when the
!    component is added to a widndow, and destroying it when it is
     removed, in backends that don't support widgets without parent
     containers). This creation and destruction should be completely
!    hidden from the outside world.
! 
!    If a setter method is called on the wrapper while the component
!    does not exist, it will have no effect.
  
     The wrapper may at any time (for instance when the native widget
!    has just been created) call the proxy's refresh method, which will
!    call all the setter methods of the wrapper in proper order
!    (e.g. setting the text before setting the selection) and with the
!    correct values. This implies that general domain knowledge about
!    the component (such as a partial ordering of the setter methods)
!    should be put in the proxy, while the wrapper is just a thin
!    adaptation layer.
  
  API Reference
  
!    This section lists the setter methods that sould be supported by
!    the various back-end wrappers. In the method signatures the type of
!    the argument is given -- the wrapper is responsible for converting
!    the arguments if needed. For instance, if a native widget only
!    supports real strings and not string-like objects, the wrapper
!    should use convert the argument to setText(text) with str(text).
!    The "type" truth refers to the integer values 0 or 1, as returned
!    by operator.truth. Colours are specified with a length-3 sequence
!    containing three nubers in the range 0-255, specifying the red,
!    green, and blue values respecively.
! 
!    Note: this is a very preliminary version. (Not quite up to date
!    wrt. the code base.)
! 
!    Common methods:
! 
!       setX(int)
!       setY(int)
!       setWidth(int)
!       setHeight(int)
!       setVisible(truth)
!       setEnabled(truth)
!       setParent(Component)
!       setBackground((int, int, int)) # Background colour
!       setForeground((int, int, int)) # Foreground colour
  
     ButtonWrapper:
  
!       setText(str)
  
     CanvasWrapper:
  
!       (No separate methods.)
  
     CheckBoxWrapper:
  
!       setText(str)
!       setOn(truth)
  
     FrameWrapper:
  
!       (No separate methods.)
  
     LabelWrapper:
  
!       setText(str)
!       setHorizAlignment(int) # 0 for left, 1 for center, 2 for right
!       setVertAlignment(int)  # 0 for top, 1 cor center, 2 for bottom
  
     ListBoxWrapper:
  
!       setItems(list) # iterable of "string-able" objects
!       setSelection(int)
!       setVScroll(int) # ?
  
     MenuWrapper:
--- 40,142 ----
     The back-end wrapper presents a unified and simple interface for
     manipulating the native widget. This is done by the proxy object,
!    through a single accessor called stateUpdate. This setter method
!    takes attribute names/values as keyword arguments. The set of
!    attributes passed through contain no redundance (i.e. not both x
!    and y, and position).
! 
!    The wrapper has four more methods: prod, destroy, and
!    getPreferredSize getMinimalSize. prod is used to make the wrapper
!    "look around" and notice the environment. One application is to
!    prod all the wrappers after the main backend event loop has been
!    entered, so they may construct their native widgets if
!    needed. destroy is used to explicitly destroy the native widget,
!    and getPreferredSize will either return None (which means that it
!    is not supported) or a pair (width, height) describing the optimal
!    size of the widget (as calculated from font sizes and
!    package-specific metrics). The method getMinimalSize works in the
!    same manner, returning what the native package would consider the
!    minimal size for the widget.
  
     The back-end wrapper installs event handlers so that it can send
!    the proper Anygui events (through the send function) as a reaction
!    to native events, and so that it can update the proxy state
!    (through the modify mehtod) whenever the native widget is modified
!    by the user.
  
     The wrapper is responsible for creating and destroying the native
     widget as needed (for instance creating the widget when the
!    component is added to a window, and destroying it when it is
     removed, in backends that don't support widgets without parent
     containers). This creation and destruction should be completely
!    hidden from the outside world. The destroy method is supplied only
!    so that the user may explicitly destroy the native widget to avoid
!    hogging resources unnecessarily. (It will then be called through
!    the proxy's destroy method.)
! 
!    If stateUpdate is called on the wrapper while the component does
!    not exist, it will have no effect. Also, the wrapper is free to
!    silently ignore any state attributes it is unable to handle. For
!    instance, a plain text backend may not be able to handle colours,
!    and should degrade gracefully in the face of a state attribute
!    which attempted to modify the foreground or background colour.
  
     The wrapper may at any time (for instance when the native widget
!    has just been created) call the proxy's refresh method. This, in
!    turn, will make the proxy call the wrapper's stateUpdate method.
  
  API Reference
  
!    This section lists the attributes that should be supported by the
!    various backend wrappers. As mentioned, this is only a guide,
!    since certain backends may not be able to support all of them
!    exactly.
! 
!    For each attribute the type of the value is given -- the wrapper is
!    responsible for converting the arguments if needed. For instance,
!    if a native widget only supports proper strings (of type str) and
!    not string-like objects, the wrapper should use convert the
!    attribute text with str(text).  The "type" truth refers to the
!    integer values 0 or 1, as returned by operator.truth.
! 
!    Common attributes:
! 
!       x: int
!       y: int
!       width: int
!       height: int
!       visible: truth
!       enabled: truth
!       parent: Component
!       background: (int, int, int) # Background colour
!       foreground: (int, int, int) # Foreground colour
  
     ButtonWrapper:
  
!       text: str
  
     CanvasWrapper:
  
!       [tbd]
  
     CheckBoxWrapper:
  
!       text: str
!       on: truth
  
     FrameWrapper:
  
!       (No separate attributes.)
  
     LabelWrapper:
  
!       text: str
!       horizAlignment: int # 0 for left, 1 for center, 2 for right (?)
!       vertAlignment: int  # 0 for top, 1 cor center, 2 for bottom (?)
  
     ListBoxWrapper:
  
!       items: list # iterable of "string-able" objects
!       selection: int
!       vScroll: int # ?
  
     MenuWrapper:
***************
*** 132,153 ****
     RadioButtonWrapper:
  
!       setText(str)
!       setOn(truth)
  
     TextAreaWrapper:
  
!       setText(str)
!       setSelection((int, int)) # (start, stop)
!       setHScroll(int) # ?
!       setVScroll(int) # ?
  
     TextFieldWrapper:
  
!       setText(str)
!       setSelection((int, int)) # (start, stop)
  
     WindowWrapper:
  
!       setTitle(str)
  
     [TBD: ComboBoxWrapper, TreeWrapper, ToolBookWrapper, ...]
--- 146,167 ----
     RadioButtonWrapper:
  
!       text: str
!       on: truth
  
     TextAreaWrapper:
  
!       text: str
!       selection: (int, int) # (start, stop)
!       hScroll: int # ?
!       vScroll: int # ?
  
     TextFieldWrapper:
  
!       text: str
!       selection: (int, int) # (start, stop)
  
     WindowWrapper:
  
!       title: str
  
     [TBD: ComboBoxWrapper, TreeWrapper, ToolBookWrapper, ...]
***************
*** 167,183 ****
     infinite recursion.)
  
!    Should the wrapper (and the proxy) have a destroy method? If a
!    native widget (e.g. a window) hogs lots of resources it might be
!    nice to be able to destroy it explicitly. Is this essential?
! 
!    To what degree can the wrapper API be generalised? There should
!    probably be two parts to it: One general part (dealing with
!    geometry, containment, text, title, etc.) and one specific part
!    (hopefully very small, dealing with component-specific
!    issues). Since each wrapper will have a dedicated proxy, there
!    should be no need for an introspection API or something similar.
! 
!    What parts of the component life cycle are not covered by this
!    architecture? How will the wrappers know when the main event loop
!    has started (whether explicitly, or implicitly in a separate
!    thread)? They will need to know, to create their native widgets.
--- 181,195 ----
     infinite recursion.)
  
!    Should backend wrappers be able to take over responsibility for
!    some attributes?
! 
!    Should it be possible to restrict what is updated?
! 
!    Should it be possible to modify native attributes (such as list box
!    items) instead of replacing them? This might be important to avoid
!    flicker and sluggishness.
! 
!    Should alias attributes be handler by giving the name to the
!    modified one to refresh, e.g. btn.refresh('geometry')? If giving
!    names like this is allowed, it could be used to restrict what is
!    passed to the backend wrapper.
\ No newline at end of file