Re: [sugar] how does an activity connect to the journal?
[EMAIL PROTECTED] schrieb: > -- > > Message: 8 > Date: Thu, 28 Feb 2008 11:57:25 -0500 > From: "Eben Eliason" <[EMAIL PROTECTED]> > Subject: Re: [sugar] how does an activity connect to the journal? > To: "Paul Fox" <[EMAIL PROTECTED]> > Cc: Sugar Mailing List > Message-ID: > <[EMAIL PROTECTED]> > Content-Type: text/plain; charset="iso-8859-1" > > On Thu, Feb 28, 2008 at 11:51 AM, Paul Fox <[EMAIL PROTECTED]> wrote: > > >> tomeu wrote: >> > >> > Yeah, it's a very important concept and perhaps it's not clearly >> > stated in the wiki documentation. Do you have any idea about how to >> > improve this? Perhaps the HIG should make this clearer? >> >> it may be there already. i need to spend some more "quality time" >> with the HIG document. >> > > > Heh, me too, and I'm the one writing (or rather, who wrote) most of it. > Unfortunately, it's been stagnant for quite some time and needs a major > refresh. I think it should still provide a pretty solid overview of all the > major concepts, though some details may not be fully accurate at this point. > Your thoughts on its current state and areas for improvement would be much > appreciated. Thanks! > As I'm currently working on the chapter about GUIs for our Activity Handbook (http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook) I've been spending quite a lot of the time on the [[HIG]] pages lately. In general I feel that they're very well written and I also always recommend them as must-read to anyone who's interested in Sugar or writing activities. Apart from the missing sections towards the end I also have a couple of other comments and suggestions: First of all I feel that the API References deserve more love. The reference entries themselves definitely need to be extended in order to be really useful to (new) developers. I've been trying to do that in the Activity Handbook by including short code-snippets for some of the things one can do with e.g. the toolbox/toolbar: --- snip --- As mentioned above the standard activity toolbar comes with both the "Share with" combo-box and the "keep"-button enabled. For situations where these elements aren't needed we can simply hide them by setting their "visible" property to "False". Below you can find a code-snippet that does exactly that: # Loads the activity toolbar activity_toolbar = toolbox.get_activity_toolbar() # Hides the "Share with:" combo-box activity_toolbar.share.props.visible = False # Hides the keep button activity_toolbar.keep.props.visible = False --- snip --- I'm not sure how much code belongs into the [[HIG]] itself (probably none!) but I definitely think that kind of information needs to be tied in by linking to relevant resources. Secondly I believe that more information about collaboration should be included. Right now for example we have many activities that come with a "share with:" button but don't actually do anything. So how much of a requirement is collaboration actually? Is it okay to have single-player games and single-user activities or should everyone really try to allow for multiple people to work on an activity? Another thing that might be useful is a list of "do"-s and "don't"-s. I'm sure that Eben and many other have come across activities that seemed to do something particularly well or not so well and these examples could be used as case-studies. Right now some elements such as the toolbars are very well explained but what at least I'm looking for is a closer explanation of how different elements should or shouldn't be tied together. All in all I believe we can all learn a lot from the mistakes that others have made. Cheers, Christoph > - Eben > > ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
On Thu, Feb 28, 2008 at 11:51 AM, Paul Fox <[EMAIL PROTECTED]> wrote: > tomeu wrote: > > > > Yeah, it's a very important concept and perhaps it's not clearly > > stated in the wiki documentation. Do you have any idea about how to > > improve this? Perhaps the HIG should make this clearer? > > it may be there already. i need to spend some more "quality time" > with the HIG document. Heh, me too, and I'm the one writing (or rather, who wrote) most of it. Unfortunately, it's been stagnant for quite some time and needs a major refresh. I think it should still provide a pretty solid overview of all the major concepts, though some details may not be fully accurate at this point. Your thoughts on its current state and areas for improvement would be much appreciated. Thanks! - Eben ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
tomeu wrote: > > Yeah, it's a very important concept and perhaps it's not clearly > stated in the wiki documentation. Do you have any idea about how to > improve this? Perhaps the HIG should make this clearer? it may be there already. i need to spend some more "quality time" with the HIG document. > > > > -- that's pretty > > > > daunting, esp. for a program that already saves a lot of state in > > > > other ways. > > > > > > In which other ways? Can you elaborate? > > > > well, like many existing non-sugar programs, this program creates > > a subdirectory in $HOME and saves some state there. it's a mapping ... > Would make sense if the file in the activity entry would be a zip file > containing all other files? > > Or those files would be somewhere else in $HOME and the entry would > contain only little bits of state? perhaps. paul =- paul fox, [EMAIL PROTECTED] (arlington, ma, where it's 23.7 degrees) ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
On Feb 28, 2008, at 17:26 , Paul Fox wrote: > > well, like many existing non-sugar programs, this program creates > a subdirectory in $HOME and saves some state there. it's a mapping > program, so things like current location on the map, current zoom > level, name of of the GPS route being followed, the current GPS > track, etc. also per-user configuration: personal landmarks, > trips, previously saved tracks, etc. (this app is clearly a long > way from being sugarized, and probably never will be.) I advocated having $HOME point to the "data" dir, but so far wasn't successful ... > i'll take a look at eToys. Hehe. You're not afraid of reading non-pretty Smalltalk code? ;) - Bert - ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
On Thu, Feb 28, 2008 at 5:26 PM, Paul Fox <[EMAIL PROTECTED]> wrote: > tomeu wrote: > > On Thu, Feb 28, 2008 at 3:10 PM, Paul Fox <[EMAIL PROTECTED]> wrote: > > > > ah -- okay -- the "Datastore" section says my app must store its > > > complete state in the datastore, to let it show up in the journal. > > > but i'm not sure what "complete state" means > > > > All the data that your activity needs to restore its UI and underlying > > model as it was when it was closed. > > okay -- i'm beginning to understand the notion of "instance" more > completely, and the notion of any past instance in time being > resumable. i didn't get that before. Yeah, it's a very important concept and perhaps it's not clearly stated in the wiki documentation. Do you have any idea about how to improve this? Perhaps the HIG should make this clearer? > > > -- that's pretty > > > daunting, esp. for a program that already saves a lot of state in > > > other ways. > > > > In which other ways? Can you elaborate? > > well, like many existing non-sugar programs, this program creates > a subdirectory in $HOME and saves some state there. it's a mapping > program, so things like current location on the map, current zoom > level, name of of the GPS route being followed, the current GPS > track, etc. also per-user configuration: personal landmarks, > trips, previously saved tracks, etc. (this app is clearly a long > way from being sugarized, and probably never will be.) Would make sense if the file in the activity entry would be a zip file containing all other files? Or those files would be somewhere else in $HOME and the entry would contain only little bits of state? Tomeu ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
On Feb 28, 2008, at 17:17 , Paul Fox wrote: > i forgot to mention -- i'm also a non-Dbus guy. :-) Well, it was new to me too when I started with Sugar ;) There's some info at http://dbus.freedesktop.org/ > how do activate/passivate (nice word :-), screenshots, invitations, > fit into the lifetime-of-an-activity view of things? Okay, I added a bit more of an explanation to the DBus Methods section. But really, the API doc page assumes you are familiar with the user's point of view - that is, you have tried sharing some activities etc. so you know what the basic model is. > is there a way to view the contents of > ~/.sugar/default/logs outside of the terminal? There's the Log Viewer activity. - Bert - ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
tomeu wrote: > On Thu, Feb 28, 2008 at 3:10 PM, Paul Fox <[EMAIL PROTECTED]> wrote: > > ah -- okay -- the "Datastore" section says my app must store its > > complete state in the datastore, to let it show up in the journal. > > but i'm not sure what "complete state" means > > All the data that your activity needs to restore its UI and underlying > model as it was when it was closed. okay -- i'm beginning to understand the notion of "instance" more completely, and the notion of any past instance in time being resumable. i didn't get that before. > > -- that's pretty > > daunting, esp. for a program that already saves a lot of state in > > other ways. > > In which other ways? Can you elaborate? well, like many existing non-sugar programs, this program creates a subdirectory in $HOME and saves some state there. it's a mapping program, so things like current location on the map, current zoom level, name of of the GPS route being followed, the current GPS track, etc. also per-user configuration: personal landmarks, trips, previously saved tracks, etc. (this app is clearly a long way from being sugarized, and probably never will be.) > > is there a minimum that i need to do / can do? and > > this is all accessed via DBUS? that's not completely clear from > > the page text. (and again, a pointer to how to figure out how > > to access the datastore/journal from non-python languages might > > be useful.) > > Some activities have already done that. One that comes to my mind is eToys. > > You certainly don't need to implement state saving to the perfection. > Having something working quickly and then keep improving would make > sense. i'll take a look at eToys. clearly a minimum of "where on the map was i?" might be good state to be able to resume. > that. The Journal is not supposed to access arbitrary data on the file > system. If you explain what you want to do with the logs someone might > be able to help. as i wrote in the other mail, it was more of an assumption that i made, that i should be able to see that data. (it's actually not very important, except to the developer. but that happens to be me. ;-) paul =- paul fox, [EMAIL PROTECTED] (arlington, ma, where it's 22.5 degrees) ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
bert wrote: > On Feb 28, 2008, at 15:10 , Paul Fox wrote: > > > > > i do feel like that there could be more of a broad-brush > > overview, something like a "Lifetime of an Activity" section, > > that would describe the interactions of an activity with the > > various other sugar services, from start to finish. this would > > put the various piece parts of the api in context. i've looked > > (mostly via backlinks from this page) for such an overview, but > > haven't found it. > > Good point. I added an attempt to explain the life cycle of an > activity to the "Overview" section. > just took a look -- that helps a lot. thanks. > > maybe much of what i need is there and i'm just not seeing it. > > i get more from the wiki pages every time i read them, and i'm > > handicapped by not being a python guy -- remember that i'm > > porting an existing non-python, non-DBUS-aware app, and just > > trying to make it run the best it can. but i also think it's > > typical of a wiki that it concentrate on the details. > > That page is actually written by a "non-python guy" for fellow "non- > python guys". It only uses pseudo-code (although that pseudo-code is > inspired by Python). i forgot to mention -- i'm also a non-Dbus guy. :-) > > > the "Dbus Methods" section starts with "An activity instance > > needs to create a DBus service", but there's no indication of > > "why?". what specific user or system interactions will be > > enabled by creating this service? what specific things won't > > work if i don't? (also, a link to somehere describing how to > > [figure out how to] create this service for non-python activities > > might be useful here.) > > The Sugar shell will (try to) call the methods listed in that > section. The rationale for each method is given there, too. okay. i guess i thought there might again be a higher level view. how do activate/passivate (nice word :-), screenshots, invitations, fit into the lifetime-of-an-activity view of things? > > For a basic understanding of what an activity is (in contrast to > regular apps), you should read > > http://wiki.laptop.org/go/HIG yes, i certainly need to read that more completely. > > back to my logs: naively, i thought that since my messages were > > already being stored under ~/.sugar/default/logs/org.x.RoadMap-3.log, > > that i'd be able to access them without much trouble from the > > Journal. but apparently that's not the case? > > Logs have nothing to do with the Datastore. right. i think i've been misled by by my own preconceptions. having said that, is there a way to view the contents of ~/.sugar/default/logs outside of the terminal? paul =- paul fox, [EMAIL PROTECTED] (arlington, ma, where it's 22.8 degrees) ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
On Feb 28, 2008, at 15:10 , Paul Fox wrote: > i wrote: >> where is the interface between activities and the journal >> documented? i'm not coming up with anything concrete when i >> search the wiki. (or alternatively, i'm coming up with too much >> to wade through.) > > two people have suggested (offlist, presumably to save me > embarrassment ;-) that i look more closely at: > http://wiki.laptop.org/go/Low-level_Activity_API > > certainly this page answers my questions about the X properties that > are being set in the preload library. > > both referrers asked if there were things missing from that page. > i'll try and comment on what i think could help someone like me. > > i do feel like that there could be more of a broad-brush > overview, something like a "Lifetime of an Activity" section, > that would describe the interactions of an activity with the > various other sugar services, from start to finish. this would > put the various piece parts of the api in context. i've looked > (mostly via backlinks from this page) for such an overview, but > haven't found it. Good point. I added an attempt to explain the life cycle of an activity to the "Overview" section. > maybe much of what i need is there and i'm just not seeing it. > i get more from the wiki pages every time i read them, and i'm > handicapped by not being a python guy -- remember that i'm > porting an existing non-python, non-DBUS-aware app, and just > trying to make it run the best it can. but i also think it's > typical of a wiki that it concentrate on the details. That page is actually written by a "non-python guy" for fellow "non- python guys". It only uses pseudo-code (although that pseudo-code is inspired by Python). > the "Dbus Methods" section starts with "An activity instance > needs to create a DBus service", but there's no indication of > "why?". what specific user or system interactions will be > enabled by creating this service? what specific things won't > work if i don't? (also, a link to somehere describing how to > [figure out how to] create this service for non-python activities > might be useful here.) The Sugar shell will (try to) call the methods listed in that section. The rationale for each method is given there, too. >> my activity starts (and terminates) okay, and anything it emits >> on stdout or stderr ends up in a log file under /home/olpc/.sugar >> (so some things are working), and it appears on the "ring of >> running apps", but it doesn't show up in the journal. > > ah -- okay -- the "Datastore" section says my app must store its > complete state in the datastore, to let it show up in the journal. > but i'm not sure what "complete state" means -- that's pretty > daunting, esp. for a program that already saves a lot of state in > other ways. is there a minimum that i need to do / can do? and > this is all accessed via DBUS? that's not completely clear from > the page text. (and again, a pointer to how to figure out how > to access the datastore/journal from non-python languages might > be useful.) For a basic understanding of what an activity is (in contrast to regular apps), you should read http://wiki.laptop.org/go/HIG And yes, DBus is a must as indicated on the very top, use whatever DBus bindings exist for your language (e.g., libdbus in the case of C). > back to my logs: naively, i thought that since my messages were > already being stored under ~/.sugar/default/logs/org.x.RoadMap-3.log, > that i'd be able to access them without much trouble from the > Journal. but apparently that's not the case? Logs have nothing to do with the Datastore. > i guess this reminds me of something else -- for someone who's > fairly new at this, the correspondence between the concepts of > "Datastore" and "Journal" isn't obvious. the wiki pages all talk > about the Datastore, but what the user sees is the Journal. (i > think this hampered my initial searches, both when skimming pages > and when actually entering searches on the wiki.) The Journal is a view onto the Datastore. > anyway -- thanks for the pointers -- i have a much better > understanding of what needs to be done, even if i still don't > know how to go about doing it. :-) i hope my comments have been > helpful -- it should be pretty clear that i'm in no position to > make additions or updates to the wiki myself, at this point. > i'll try and help where and when i can, however. Yes, your feedback is welcome. Thanks! - Bert - ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
Re: [sugar] how does an activity connect to the journal?
On Thu, Feb 28, 2008 at 3:10 PM, Paul Fox <[EMAIL PROTECTED]> wrote: > i wrote: > > where is the interface between activities and the journal > > documented? i'm not coming up with anything concrete when i > > search the wiki. (or alternatively, i'm coming up with too much > > to wade through.) > > two people have suggested (offlist, presumably to save me > embarrassment ;-) Sorry, have changed MUAs recently and haven't got used to the Reply to all button yet :/ Nothing to feel embarrassed that I can see ;) > that i look more closely at: > > http://wiki.laptop.org/go/Low-level_Activity_API > > certainly this page answers my questions about the X properties that > are being set in the preload library. > > both referrers asked if there were things missing from that page. > i'll try and comment on what i think could help someone like me. Thanks, that's very much needed. > i do feel like that there could be more of a broad-brush > overview, something like a "Lifetime of an Activity" section, > that would describe the interactions of an activity with the > various other sugar services, from start to finish. this would > put the various piece parts of the api in context. i've looked > (mostly via backlinks from this page) for such an overview, but > haven't found it. Looks like a good idea. Do you have enough info for starting it? I will be glad to answer all questions. > maybe much of what i need is there and i'm just not seeing it. Don't think so, there's very little manpower available for development, less for documentation. > i get more from the wiki pages every time i read them, and i'm > handicapped by not being a python guy -- remember that i'm > porting an existing non-python, non-DBUS-aware app, and just > trying to make it run the best it can. but i also think it's > typical of a wiki that it concentrate on the details. You are right again, non-python developers are in disadvantage because the higher level APIs have been coded in python as is much faster to write and easier to maintain. We would like to be able to rewrite them in C so these APIs can be accessed from other languages. > the "Dbus Methods" section starts with "An activity instance > needs to create a DBus service", but there's no indication of > "why?". what specific user or system interactions will be > enabled by creating this service? what specific things won't > work if i don't? (also, a link to somehere describing how to > [figure out how to] create this service for non-python activities > might be useful here.) Yes, other people have observed before that the documentation should also explain the rationales behind the design decisions. > > my activity starts (and terminates) okay, and anything it emits > > on stdout or stderr ends up in a log file under /home/olpc/.sugar > > (so some things are working), and it appears on the "ring of > > running apps", but it doesn't show up in the journal. > > ah -- okay -- the "Datastore" section says my app must store its > complete state in the datastore, to let it show up in the journal. > but i'm not sure what "complete state" means All the data that your activity needs to restore its UI and underlying model as it was when it was closed. > -- that's pretty > daunting, esp. for a program that already saves a lot of state in > other ways. In which other ways? Can you elaborate? > is there a minimum that i need to do / can do? and > this is all accessed via DBUS? that's not completely clear from > the page text. (and again, a pointer to how to figure out how > to access the datastore/journal from non-python languages might > be useful.) Some activities have already done that. One that comes to my mind is eToys. You certainly don't need to implement state saving to the perfection. Having something working quickly and then keep improving would make sense. > back to my logs: naively, i thought that since my messages were > already being stored under ~/.sugar/default/logs/org.x.RoadMap-3.log, > that i'd be able to access them without much trouble from the > Journal. but apparently that's not the case? The Journal is the graphical front end of the datastore. The datastore is a service that stores data and metadata and performs queries on that. The Journal is not supposed to access arbitrary data on the file system. If you explain what you want to do with the logs someone might be able to help. > i guess this reminds me of something else -- for someone who's > fairly new at this, the correspondence between the concepts of > "Datastore" and "Journal" isn't obvious. the wiki pages all talk > about the Datastore, but what the user sees is the Journal. (i > think this hampered my initial searches, both when skimming pages > and when actually entering searches on the wiki.) > > anyway -- thanks for the pointers -- i have a much better > understanding of what needs to be done, even if i still don't > kno
Re: [sugar] how does an activity connect to the journal?
i wrote: > where is the interface between activities and the journal > documented? i'm not coming up with anything concrete when i > search the wiki. (or alternatively, i'm coming up with too much > to wade through.) two people have suggested (offlist, presumably to save me embarrassment ;-) that i look more closely at: http://wiki.laptop.org/go/Low-level_Activity_API certainly this page answers my questions about the X properties that are being set in the preload library. both referrers asked if there were things missing from that page. i'll try and comment on what i think could help someone like me. i do feel like that there could be more of a broad-brush overview, something like a "Lifetime of an Activity" section, that would describe the interactions of an activity with the various other sugar services, from start to finish. this would put the various piece parts of the api in context. i've looked (mostly via backlinks from this page) for such an overview, but haven't found it. maybe much of what i need is there and i'm just not seeing it. i get more from the wiki pages every time i read them, and i'm handicapped by not being a python guy -- remember that i'm porting an existing non-python, non-DBUS-aware app, and just trying to make it run the best it can. but i also think it's typical of a wiki that it concentrate on the details. the "Dbus Methods" section starts with "An activity instance needs to create a DBus service", but there's no indication of "why?". what specific user or system interactions will be enabled by creating this service? what specific things won't work if i don't? (also, a link to somehere describing how to [figure out how to] create this service for non-python activities might be useful here.) > my activity starts (and terminates) okay, and anything it emits > on stdout or stderr ends up in a log file under /home/olpc/.sugar > (so some things are working), and it appears on the "ring of > running apps", but it doesn't show up in the journal. ah -- okay -- the "Datastore" section says my app must store its complete state in the datastore, to let it show up in the journal. but i'm not sure what "complete state" means -- that's pretty daunting, esp. for a program that already saves a lot of state in other ways. is there a minimum that i need to do / can do? and this is all accessed via DBUS? that's not completely clear from the page text. (and again, a pointer to how to figure out how to access the datastore/journal from non-python languages might be useful.) back to my logs: naively, i thought that since my messages were already being stored under ~/.sugar/default/logs/org.x.RoadMap-3.log, that i'd be able to access them without much trouble from the Journal. but apparently that's not the case? i guess this reminds me of something else -- for someone who's fairly new at this, the correspondence between the concepts of "Datastore" and "Journal" isn't obvious. the wiki pages all talk about the Datastore, but what the user sees is the Journal. (i think this hampered my initial searches, both when skimming pages and when actually entering searches on the wiki.) anyway -- thanks for the pointers -- i have a much better understanding of what needs to be done, even if i still don't know how to go about doing it. :-) i hope my comments have been helpful -- it should be pretty clear that i'm in no position to make additions or updates to the wiki myself, at this point. i'll try and help where and when i can, however. paul =- paul fox, [EMAIL PROTECTED] (arlington, ma, where it's 16.7 degrees) ___ Sugar mailing list Sugar@lists.laptop.org http://lists.laptop.org/listinfo/sugar
