[Reality] Faucet API & class, round 1

[Michael Dartt]

Clarification: the GUI API is basically us saying, "If you write a
front-end, could you please name your functions and variables/widgets/etc.
according to these guidelines?"  So it's really just an interface--no
official code to go with it.

The criteria I used for splitting stuff up was that the GUI stuff only
deals with toolkit-specific issues--widgets, displaying info, etc.  The
Faucet module will handle the manipulation and storage of the information,
since that's common to all clients, no matter what toolkit is being used.
Finally, the front-end won't be ignorant of the stuff in Faucet.py, b/c
it'll inherit from it.

The point of this is to make it easier to develop Faucets--the only thing
one has to do is write the GUI code.

As far as merging Faucet.py with FaucetProtocol, I'm a bit leery of that
b/c the protocol implies the means by which the Faucet interacts with the
Pump, rather than how the Faucet operates internally.

Does this clear things up?


--Mike


On Thu, 16 Mar 2000, Glyph Lefkowitz wrote:

> 
> Good idea, but I don't think as many parts of this are generalizable as
> you think; but let me address each one specifically.
> 
> On Thu, 16 Mar 2000, Michael Dartt wrote:
> 
> > Faucet class (faucet.py): contains structures, functions, etc. common to
> > all Faucets, regardless of front-end, excepting networking/protocol stuff,
> > which will go in protocol.py
> 
> Well, it might be better to just put the 'common' stuff in protocol.py,
> since the protocol should ideally not only define the bytes being sent
> over the wire, but the higher-level *meaning* of those bytes... however...
> 
> > Faucet GUI API: function and variable names and construction, so that
> > it'll be easier to write, read, and debug Faucet front-ends (assuming
> > programmers follow this :-j)
> 
> Well, this exists to some extent already.  I mean, the name, hears,
> et. al. methods are there... there are things to implement to do all of
> the major functions, and as it gets complete, more of those will
> appear.  FaucetProtocol defines this.
> 
> > The inheritance structure would go: FaucetProtocol -> Faucet -> GUIFaucet
> > (e.g. GtkFaucet, TkFaucet, NcursesFaucet, etc.)
> 
> You might want to eliminate the first or second link in this chain
> (depending on how you want to do naming) , for the reasons I gave above...
> 
> > Below are my lists for what I think should go into the two things I've
> > mentioned above.  Let me know what needs changing.  (Or if there are any
> > suggestions....)
> 
> Will do :-)
> 
> > Functions are denoted with a dollar sign ($).  The other symbols have no
> > significance.  (It's all indentation.  :-)
> 
> "It's all about the whitespace, baby..."
> 
> > --Mike
> > ------
> > 
> > * Common stuff (Faucet.py)
> > 	- history
> > 	  $ history up
> > 	  $ history down
> > 	  $ save history
> 
> All good stuff.  This can definitely be generalized.
> 
> > 	- keys
> > 	  - shortcuts (keypad #s for moving, other user-defined, etc) dict
> > 	  - expansions ("u" for "go up", etc.) dict
> > 	  - etc. (Return, Up, Down, et al) dict
> > 	  $ load shortcuts, etc.
> > 	  $ change shortcuts
> > 	  $ key functions (what Return, et al do)
> 
> Also not bad.
> 
> > 	- items dictionary
> > 	  $ refresh
> > 	  $ add items
> > 	  $ remove items
> > 	  $ clear	  
> 
> Aah, here we get into a problem.
> 
> The GUI frontend is going to need to know about add/removes, especially if
> we're going to put the items display into a tree (GtkCTree) or list
> (GtkCList).  Not to mention the hariness of doing this in
> ncurses.  I don't know if keeping the dictionary around will always be
> useful... or if it is, to what degree... different formats of storage may
> prove useful here.
> 
> > 	- description dictionary
> > 	  $ refresh
> > 	  $ add key
> > 	  $ remove key
> > 	  $ clear
> 
> OK, this could quite possibly be generic, since there's no need for
> elements of the description to be distinct to the player...
> 
> > 	- exits list
> > 	  $ add exits to desc
> 
> This not so much.  I'd ideally like to have a graphical compass of some
> kind at some point... the exits in the room desc was always supposed to be
> temporary (but it's been around so long it's grown into a kind of de facto
> standard)
> 
> > * UI pieces (API)
> > 	- Login window
> <snip>
> 
> Why do we need an API to access login-windows?  I can't see a reason that
> that would be helpful in-game...
> 
> > 	  @ "save password" check box
> > 	    - label
> 
> Uh... I dunno... the little security demon in my head is screaming about
> that one ;)
> 
> > 	  @ "auto-login" check box
> > 	    - label
> 
> This too ... but I guess AIM does it... hm.
> 
> > 	  $ save fields & prefs
> 
> OK...
> 
> > 	- Game window
> 
> <snip>
> 
> When you say "API", what do you mean here?  What I was thinking you meant
> was entry points for the "gui plugins" that Dave and I suggested, but it
> looks like you're talking about something different... what programmers
> would be using this API?
> 
> > 	- Authoring window
> > 	  @ window title
> > 	  @ OK button
> > 	    - button label
> > 	  @ Cancel button
> > 	    - button label
> > 	  @ Clear button
> > 	    - button label
> > 	  @ text field 
> > 	  $ get text from box
> 
> well, this would be useful in any case...
> 
> > * Save following in Faucet dir (one file, XML?):
> 
> Ooh yes, let's use XML!  It will be dynamic and efficient and
> multithreaded and enterprise wide!  Not to mention scalable and
> multi-architectured and hluaghlaughlauglhagluahg (ad infinitum).
> 
> No, I think that a nice, simple tab-delimited text file will be fine
> :-) those were a standard long before XML got its claws into the lives and
> sanity of programmers everywhere.  And, as in most places where XML is
> suggested, we need none of its features and it would probably just serve
> to make things slow and stupid.
> 
> On a more positive XML-type note, it might be a nice thing to use for the
> map format, if pickle doesn't scale well ... and it would be nice to have
> something slightly more human-readable... I know you're probably looking
> at all those wonderfully easy-to-use XML APIs in python and wondering what
> to do with them.  So am I :)
> 
>                       ______      __   __  _____  _     _
>                      |  ____ |      \_/   |_____] |_____|
>                      |_____| |_____  |    |       |     |
>                      @ t w i s t e d m a t r i x  . c o m
>                      http://www.twistedmatrix.com/~glyph/
> 
> 
> 
> 
> 
> 
> 
> _______________________________________________
> Reality mailing list
> Reality@twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/reality
>