Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site
Search in forums












SourceForge.net Logo
Home » U++ Library support » U++ Widgets - General questions or Mixed problems » DOCU: Ctrl design concepts
DOCU: Ctrl design concepts [message #28346] Mon, 30 August 2010 10:26 Go to next message
kohait00 is currently offline  kohait00
Messages: 934
Registered: July 2009
Location: Germany
Experienced Contributor
hey guys,

i'm trying to summ up things that a have learned so far cencerning development of own Ctrl's, where to pay attention and on what to take care. help this one to go to manual / documentation..i think it's rather important, since own widgets are a quite common demand and everyone tries to find its own way and pace with it. but outlining some design concepts (from the makers, not from me Smile would ease the task drastically, and example code sometimes is hard to understand from the beginning. but knowing some things before (and beeing able to recognize them in actual code later) helps a lot. so here is some of the things.. please add the rest or suggest on what more need to go there

////////


Ctrl Design Concepts

When developing own Ctrl's one often is 'reinventing' the wheel, because there are common patterns to do in your Ctrl that Ultimate++ is probably already providing in Ctrl base class. Thus, knowing the base class and some of its key design concepts can make your life esier and the development of your Ctrl faster, while focusing more on the problem than the methods. As always, the best reference for Ctrl is its source code, which is quite large, thats why I try to sumerize some of the usefull things you can already use. In any case, look at the virtual functions in Ctrl to see what is meant to be implemented or used by you. I won't cover LogPos related things here, it is covered in another docu.

Generally, a Ctrl in Upp is helper to visualize some kind of data. The data, though, is not static, and can be changed from GUI (point and click) perspective or from API perspective, using manipulating functions. The difference is, that GUI interaction should modify the internal data (or state) of Ctrl AND notify application somehow about change, but modifying it using API should NOT generate change notifications. This is a very important design rule that keeps you away from a lot of head ache from recursive invokations when modifying Ctrl's in API.

Ctrl Tree

Ultimate++ uses a linked list for all the child Ctrl's that have been Add()ed to it, partaking of its drawing space. The Ctrl does NOT own its children, but simply references them (Ptr<Ctrl>). They should be owned by your appliction, somewhere in a U++ container, i.e. Array<Label> or they are already made members of your app when using Layout files. If a Ctrl is added to another, it is ensured to be properly removed from its previous parent, thus a Ctrl cant be part of 2 trees.

GetData / SetData

Most Ctrl's you will ever create will only need one single value to visualize or represent. This is true for EditFields, Buttons, Labels, etc. To be able to Get / Set this single value into/from the Ctrl, Upp uses it's own 'polymorphic' Value class (see another docu), which enables the Ctrl's to receive and handle intrinsic dataypes internally through one single interface, reliefing you from the convertion pain. That's why exsists GetData / SetData pair. it is the main door into your Ctrl. Even more complex Ctrl's like TreCtrl use it to provide the currently selected index. Think of your Ctrl, which information it could provide as general through this interface. it makes implicit usage easy, also in terms of notification (see next)

WhenAction Callback

To notify upper layers of some changes, your Ctrl can use internally (or the user externally) the Action() function, which will call WhenCallback. and provide the feedback This is the Callback that can be set using '<<= THISBACK()' approach, so using it for your own Ctrl is preferable, since it leads to Upp conform short syntaxes. Be carefull to only call Action() inside your code upon graphical user interaction. When modifiing your Ctrl from API, it should generate no Action(). More or diverse notifications can be provided in your controls using other global Callbacks (or even Callback1<yourtype> or more), if needed. Use the WhenSomething name convention to reflect Event behaviour.

Updated(), SetModify(), ResetModify(), ClearModify(), IsModified()

Often, the control needs to process or calculate other things based on the change of some data inside the control (like maybe some results, cached values or the like, NOT graphical helper data, this is done using Layout() which is invoked when resizing or opening the Ctrl). Use the Updated() virtual function to realize this, because it can be triggered from 'outside' using the Update() function. It also SetModified()'s your Ctrl, so you can check for it. Often, when data is changed, Ctrl needs to be updated somehow calculating its things and then the user needs to be notified. UpdateAction() does this in one step, calling both. If graphical data needs change as well, UpdateActionRefresh() is the chain to go, which will invoke an additional Paint(). ClearModify() acts recursively on all children too.

Accept / Reject

lorem ipsum Smile

Layout

lerem ipsum

////////////
Re: DOCU: Ctrl design concepts [message #29270 is a reply to message #28346] Wed, 13 October 2010 19:25 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 11993
Registered: November 2005
Ultimate Member
Sounds good. Why do not you add this to CtrlLib docs?
Re: DOCU: Ctrl design concepts [message #29280 is a reply to message #29270] Wed, 13 October 2010 21:54 Go to previous messageGo to next message
kohait00 is currently offline  kohait00
Messages: 934
Registered: July 2009
Location: Germany
Experienced Contributor
it is already there Smile

CtrlCore/srcdoc/CtrlDesignConcepts

but it is still to be extended...i'd like to know more on that myself..if you know more please extend..

maybe a little more on frame behaviour, 'dirty' behaviour, data behaviour.. Display, Converter, Value etc.. DHCtrl (which I dont know anything about for now)
Re: DOCU: Ctrl design concepts [message #29331 is a reply to message #29280] Fri, 15 October 2010 14:42 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 11993
Registered: November 2005
Ultimate Member
[quote title=kohait00 wrote on Wed, 13 October 2010 15:54DHCtrl (which I dont know anything about for now)[/quote]

DHCtrl is just a bridge between U++ and "system child windows", like GLCtrl...
Re: DOCU: Ctrl design concepts [message #29514 is a reply to message #29331] Mon, 25 October 2010 16:12 Go to previous messageGo to next message
kohait00 is currently offline  kohait00
Messages: 934
Registered: July 2009
Location: Germany
Experienced Contributor
i was wrong, it hasnt yet been added. just did it.
Re: DOCU: Ctrl design concepts [message #29795 is a reply to message #29514] Wed, 17 November 2010 17:27 Go to previous messageGo to next message
kohait00 is currently offline  kohait00
Messages: 934
Registered: July 2009
Location: Germany
Experienced Contributor
hi mirek,

could you spot some light on the Accept() / Reject() behaviour?
i dont quite get it yet. reading the documentation does not clear the questions very well.

and one more: which controls so far do use the ValueArray?
i imagine of ArrayCtrl, which probably uses it to insert multiple values as row..
Re: DOCU: Ctrl design concepts [message #29890 is a reply to message #29795] Sat, 27 November 2010 18:41 Go to previous message
mirek is currently offline  mirek
Messages: 11993
Registered: November 2005
Ultimate Member
kohait00 wrote on Wed, 17 November 2010 11:27

hi mirek,

could you spot some light on the Accept() / Reject() behaviour?
i dont quite get it yet. reading the documentation does not clear the questions very well.



The primar motivation is that on many dialogs, once you press OK button, some widgets should "finish" processing. E.g. widget contains some database data, which are edited and they need to be written to DB.

Also, during this processing, it can be impossible to continue, because data are somewhat invalid. That is why there is a 'bool' return value - if first Accept returns false, "OK" is canceled (and typically user stays in dialog).

Then, as we already have this return value, Accept is also used to simply check the content of widget. E.g. if there is invalid date in EditDate, Accept shows error message and returns false.

Default implementation simply calls Accept for all children, returns false as soone as first returns false, if all return true, returns true.

Reject is simply Accept counterpart for Cancel button. As the whole dialog is rejected, it does not need to return any value. Reject is much less often implemented.

When speaking of "OK" and "Cancel", I describe the default (and typical) behaviour/usage. Of course, Accept/Reject can be used outside this scope.

Quote:


and one more: which controls so far do use the ValueArray?
i imagine of ArrayCtrl, which probably uses it to insert multiple values as row..


Yes. Anyway, controls do not need to use it explicitly, quite often ValueArray is used in client code as means to 'transport' some data to Convert and/or Display.

Speaking about ArrayCtrl, it actually creates ValueMap (but you can get ValueArray from ValueMap).
Previous Topic: widget or source code to handle dicom files
Next Topic: NEW: LogPosCtrl, for editing LogPos of a Ctrl
Goto Forum:
  


Current Time: Fri Aug 23 07:01:14 CEST 2019

Total time taken to generate the page: 0.01910 seconds