It's so hard to write example applications
-
What features would you like to show in the example application?
Our Forgotten Astronomy | Object Oriented Programming with C++ | Wordle solver
Basically I just want to run the entire API through it's paces. Showing each control, maybe how to build a custom control, handling multiple screens, etc.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
Keep in mind that most API documentation never presents anything anywhere close to a working "application"; they're just snippets that illustrate how to provide input parameters and look at the output (*if* they bother). And no error-checking. I'm not saying this is what you should strive for...I'm saying your samples shouldn't necessarily include much code that doesn't deal with invoking your APIs, and leave it at that.
Yeah. That's actually the challenging part, and why I feel directionless about it. Coding for its own sake, kind of. Going through some motions without a clear set of application requirements, other than the code must be simple and demonstrate the featureset. Like, I put a push_button on the screen, but clicking it does what? It's all kinds of little niggling details like that. It's death by a thousand cuts.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
Yeah. That's actually the challenging part, and why I feel directionless about it. Coding for its own sake, kind of. Going through some motions without a clear set of application requirements, other than the code must be simple and demonstrate the featureset. Like, I put a push_button on the screen, but clicking it does what? It's all kinds of little niggling details like that. It's death by a thousand cuts.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
Yeah. That's actually the challenging part, and why I feel directionless about it. Coding for its own sake, kind of. Going through some motions without a clear set of application requirements, other than the code must be simple and demonstrate the featureset. Like, I put a push_button on the screen, but clicking it does what? It's all kinds of little niggling details like that. It's death by a thousand cuts.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
Do you have tests? You could use those as a base for the API snippet kind of thing. Or I have no idea what I'm talking about.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
-
I'm writing some examples for using my UIX library. It's unexpectedly challenging. I've created real world apps using it in less time than this. The difficult bit is making it not feel too contrived while at the same time making the code simple enough to understand. It's not writing simple code that's difficult, it's coming up with a simple application, that's nevertheless complicated enough to illustrate core concepts. It's so much easier when I have a direct purpose to my application, rather than dealing in the meta and writing it for its own sake. It makes me feel rudderless. Like, what is it even supposed to do other than exist? :confused:
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
honey the codewitch wrote:
I'm writing some examples for using my UIX library
1. Provide reference documentation for the library. 2. Identify common tasks or objectives of your library's users. What are they using it for? 3. Write correct, fairly minimal sequences of library calls required to perform each of those tasks. Work hard at keeping frills and options out the examples, except as "You can also do this:" sections at the end of each one. I don't think the examples in the documentation need to be complete applications, since that can make it be easy for your user to get lost in the forest. To guarantee that they work correctly, you'll need to make a fairly complete application around them to ensure your sequences work as expected, but that application doesn't need to be in the example documentation (you can certainly include it in the distribution for the library). Oh, and by the way: include lots and lots of screen captures of what they should see, preferably from live examples.
Software Zen:
delete this; -
Yeah. That's actually the challenging part, and why I feel directionless about it. Coding for its own sake, kind of. Going through some motions without a clear set of application requirements, other than the code must be simple and demonstrate the featureset. Like, I put a push_button on the screen, but clicking it does what? It's all kinds of little niggling details like that. It's death by a thousand cuts.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
honey the codewitch wrote:
Like, I put a push_button on the screen, but clicking it does what?
It takes you to the next control example screen. If you have a text input, it won't take you to the next screen unless the user enters whatever text you select. Each screen's completion just takes you to the next control. That's it.
Our Forgotten Astronomy | Object Oriented Programming with C++ | Wordle solver
-
honey the codewitch wrote:
Like, I put a push_button on the screen, but clicking it does what?
It takes you to the next control example screen. If you have a text input, it won't take you to the next screen unless the user enters whatever text you select. Each screen's completion just takes you to the next control. That's it.
Our Forgotten Astronomy | Object Oriented Programming with C++ | Wordle solver
David O'Neil wrote:
If you have a text input
The device I'm targeting for the example has no keyboard, no USB input, and a 320x240 touchscreen. I admit I chuckled at the thought. :-D I finally figured it out. It just took a lot longer than the code would suggest.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
Do you have tests? You could use those as a base for the API snippet kind of thing. Or I have no idea what I'm talking about.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated. I’m begging you for the benefit of everyone, don’t be STUPID.
I don't yet. I should do TDD, I know, but my GFX lib is nearly impossible to unit test due to the surface area, and so when I built UIX on top of it, I just ad hoc tested it the way I did GFX. I *do* have *some* unit tests for GFX now, but not a lot of code coverage. On the bright side they're ran before the lib is published. For UIX I don't even have CI/CD going yet. That's next, then I'll write some unit tests using the PIO and Unity test framework.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
David O'Neil wrote:
If you have a text input
The device I'm targeting for the example has no keyboard, no USB input, and a 320x240 touchscreen. I admit I chuckled at the thought. :-D I finally figured it out. It just took a lot longer than the code would suggest.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
So make an onscreen keyboard that would obviously make use of scrollers? That code should be helpful to users trying to learn your system.
Our Forgotten Astronomy | Object Oriented Programming with C++ | Wordle solver
-
So make an onscreen keyboard that would obviously make use of scrollers? That code should be helpful to users trying to learn your system.
Our Forgotten Astronomy | Object Oriented Programming with C++ | Wordle solver
320x240 isn't really realistic for that. Devices this small typically don't have text input. They usually receive information like that via a cloud or bluetooth connection.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
I'm writing some examples for using my UIX library. It's unexpectedly challenging. I've created real world apps using it in less time than this. The difficult bit is making it not feel too contrived while at the same time making the code simple enough to understand. It's not writing simple code that's difficult, it's coming up with a simple application, that's nevertheless complicated enough to illustrate core concepts. It's so much easier when I have a direct purpose to my application, rather than dealing in the meta and writing it for its own sake. It makes me feel rudderless. Like, what is it even supposed to do other than exist? :confused:
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
I created "devices in software" (slaves) for my process control sofware before getting the actual devices; polling them for "real time data" to chart, etc.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
-
I'm writing some examples for using my UIX library. It's unexpectedly challenging. I've created real world apps using it in less time than this. The difficult bit is making it not feel too contrived while at the same time making the code simple enough to understand. It's not writing simple code that's difficult, it's coming up with a simple application, that's nevertheless complicated enough to illustrate core concepts. It's so much easier when I have a direct purpose to my application, rather than dealing in the meta and writing it for its own sake. It makes me feel rudderless. Like, what is it even supposed to do other than exist? :confused:
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
When trying to illustrate by example my super-duper library, I found that in addition to this being surprisingly difficult, also that (1) parts of my interface were illogical and (2) a huge chunk of functionality was missing. So, I had to go back to the workbench and code. Six months later I found it a lot easier to write the examples and instructions. It seems that test-first gives your code one kind of perfection, while explain-at-last will take your code to yet another level. Thus the two cycles, test-code and explain-code, seems to complement each other.
-
I'm writing some examples for using my UIX library. It's unexpectedly challenging. I've created real world apps using it in less time than this. The difficult bit is making it not feel too contrived while at the same time making the code simple enough to understand. It's not writing simple code that's difficult, it's coming up with a simple application, that's nevertheless complicated enough to illustrate core concepts. It's so much easier when I have a direct purpose to my application, rather than dealing in the meta and writing it for its own sake. It makes me feel rudderless. Like, what is it even supposed to do other than exist? :confused:
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
For a graphic UI as broad as UIX library I would not try to cover all. Even for simpler libraries I do not cover all functionality. The goal of examples is imho to give enough information so people can get started. So for the UIX I would think of the following mini applications - metrics converter (buttons, select boxes, text boxes, ...) the underlying math is simple so wont distract. - a color wheel selection (needs some graphics putpixel/getpixel) and maybe add an RGB LED to it. - an icon editor, or font editor (more complex) - a weather station - with functions that generate random data (can be a wrapper around BME280 et al) - pong game - fractal visualizer, e.g. tree's - Mandelbrod set - signal visualizer (poor mans oscilloscope) - jpeg viewer Then not all examples need to be available from start, take your time and add on request or when time permits. my 2 cents
-
For a graphic UI as broad as UIX library I would not try to cover all. Even for simpler libraries I do not cover all functionality. The goal of examples is imho to give enough information so people can get started. So for the UIX I would think of the following mini applications - metrics converter (buttons, select boxes, text boxes, ...) the underlying math is simple so wont distract. - a color wheel selection (needs some graphics putpixel/getpixel) and maybe add an RGB LED to it. - an icon editor, or font editor (more complex) - a weather station - with functions that generate random data (can be a wrapper around BME280 et al) - pong game - fractal visualizer, e.g. tree's - Mandelbrod set - signal visualizer (poor mans oscilloscope) - jpeg viewer Then not all examples need to be available from start, take your time and add on request or when time permits. my 2 cents
Won't be any text editors or font editors on these, as they usually have 320x240 or smaller screens, no keyboards, and kilobytes of RAM. :) That said, I will consider your suggestions in light of that. Thank you.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
Push the button and it disappears. Then two more buttons appear...
- I would love to change the world, but they won’t give me the source code.
-
When trying to illustrate by example my super-duper library, I found that in addition to this being surprisingly difficult, also that (1) parts of my interface were illogical and (2) a huge chunk of functionality was missing. So, I had to go back to the workbench and code. Six months later I found it a lot easier to write the examples and instructions. It seems that test-first gives your code one kind of perfection, while explain-at-last will take your code to yet another level. Thus the two cycles, test-code and explain-code, seems to complement each other.
In a subsequent post I wrote something similar. :laugh:
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
-
I'm writing some examples for using my UIX library. It's unexpectedly challenging. I've created real world apps using it in less time than this. The difficult bit is making it not feel too contrived while at the same time making the code simple enough to understand. It's not writing simple code that's difficult, it's coming up with a simple application, that's nevertheless complicated enough to illustrate core concepts. It's so much easier when I have a direct purpose to my application, rather than dealing in the meta and writing it for its own sake. It makes me feel rudderless. Like, what is it even supposed to do other than exist? :confused:
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
I always start with relational tables Alpha, Beta, Choice, Photo, and User. Beta has a foreign key to Alpha, Photo has a foreign key to Beta, Choice is for DDLs in either Alpha or Beta, All tables have foreign keys to User. Then let creativity flow.
-
David O'Neil wrote:
If you have a text input
The device I'm targeting for the example has no keyboard, no USB input, and a 320x240 touchscreen. I admit I chuckled at the thought. :-D I finally figured it out. It just took a lot longer than the code would suggest.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
honey the codewitch wrote:
The device I'm targeting for the example has no keyboard, no USB input, and a 320x240 touchscreen
So, if it's a common user control library you're trying to demonstrate (sorry if I've misread the thread), then David's idea makes a lot of sense, draw a control, attach a simple Hello World callback, just to demonstrate how to respond to it being used, and have a Next button to move to the page which shows another control. If it's all touch, with no room to display a virtual keyboard...then it all depends on what sort of user input the control is supposed to provide. But having your sample code show how to (a) draw the control and (b) respond to events that it raises, should pretty much cover it, IMO. An app that shows controls for the sake of showing controls sometimes *is* exactly what you need, as opposed to a real-world app that attempts to solve real-world problems. At least that would be my expectation.
-
Won't be any text editors or font editors on these, as they usually have 320x240 or smaller screens, no keyboards, and kilobytes of RAM. :) That said, I will consider your suggestions in light of that. Thank you.
Check out my IoT graphics library here: https://honeythecodewitch.com/gfx And my IoT UI/User Experience library here: https://honeythecodewitch.com/uix
honey the codewitch wrote:
they usually have 320x240 or smaller screens, no keyboards, and kilobytes of RAM
I cut my teeth on the Commodore 64, which had 320x200, less usable memory, and no touch screen. I'm sure you could get "inspired" by looking at retro software.
-
honey the codewitch wrote:
they usually have 320x240 or smaller screens, no keyboards, and kilobytes of RAM
I cut my teeth on the Commodore 64, which had 320x200, less usable memory, and no touch screen. I'm sure you could get "inspired" by looking at retro software.