transfer from internal tree r5311 branches/1.4-gpl

[xonotic/netradiant.git] / docs / developer / Inspector / inspector.txt

OK. Again I would have liked to get a design document before it being done. Main functionalities we\r
need in the inspector:\r
\r
- Unifiy the inspector under a single dialog box, called with 'S'\r
\r
- Depending on what is currently selected, display several frames in the inspector:\r
only brushes -> surface inspector\r
only patches -> patch inspector\r
brushes & patches -> both\r
and later when brush primitives are mixed with regular brushes + plugin entities, raise whatever\r
additional inspector stuff we need\r
\r
- The camera view must update realtime when we change some parameters.\r
\r
- Get rid of the Apply button, use the Undo code to store settings when surface inspector is\r
raised. If user hits Cancel, call the undo stuff.\r
\r
- Use the message broadcasting stuff to keep the inspectors up to date when the user changes the\r
current selection. Be careful to keep the undo stuff in sync with the select / deselect operations.\r
\r
- Use a 3-state scheme to display the params in the widgets. If two faces are selected that don't\r
have the same shift increment, just grey out the shift box.\r
\r
Messaging:\r
- a good chunk of the work is moving the selection/creation stuff to the messaging API\r
  we no longer use UpdateSurfaceDialog, we post messages instead ..\r
  the surface inspector has hooked one of it's listeners into the corresponding message\r
  we may need to reorganize the messages, maybe introduce a hierarchy? \r
  or pass a void * param with messages?\r
\r
- we don't post messages like "update surface inspector", we post messages that say "this and that\r
have changed", then the surface inspector reacts if it needs to.\r
Do we need marshalling in the messages? Very likely .. maybe using Gtk signal stuff would be interesting?\r
\r
-> the messaging stuff is a big chunk of work and our surface inspector changes are not totally \r
dependent on it. Better leave that for l8r\r
\r
the inspector works by states and transitions? Or we post messages to it?\r
Use case:\r
the user raises the inspector .. if we are up we'll ignore, if we are hidden we'll\r
go through the whole process (initialise, look at what is selected, display)\r
then we enter an active state (listening for select / deselects and applying stuff)\r
\r
all in all it seems to be too big a change for next release. will see later probably.\r
Trying a few more days with it, see what happens. after all the interface is fairly restricted\r
so there's a good chance our changes are fairly stable in the end. But rebuilding the whole interface\r
part might be too much ...\r
We need something state based? AND a set of messages ..\r
but first, need to write the initialisation loop\r
build the dialog, get the current surface information and display\r
\r
Undoing the changes on the selected stuff:\r
at any point in time, one can get a snapshot of selected stuff and use it to store the surface\r
properties settings for later on. But what happens if the user modifies the selected brush, pushing\r
it in the undo stack? Then we would cancel the changes? (and just backup to the state right after\r
the modif)\r
We could has the 'Apply' button used for that .. grey it out when the current state is the one in\r
the backup. This happens whenever we hit 'Apply' or change something in the selection.\r
The selection has several items: entities, brushes and selected faces (possibly later generic plugin entities)\r
Current undo stuff is aimed at entities and brushes.\r
NOTE: you can't have selected faces and brushes/entities at the same time, that's a good point to\r
keep that seperated to deal with undo and storage\r
On what side should the implemetation be ? undo.cpp select.cpp or surfacedialog.cpp ?\r
We are going to do it with the messaging API anyway..\r
And hook in the undo stuff, to reset the snapshot each time something gets pushed in the undo?\r
\r
We have advanced stuff on the Inspector branch, doing basics on Alpha branch.\r
Start writing the watch code in surfacedialog.cpp, see if we need some merging with Undo stuff l8r\r
We need to track for the patch inspector as well..\r
\r
basic code for CSurfaceUndo written. need to add hooks for the snapshot stuff and undo stuff. and a\r
debug flag to monitor the life cycle of the object.\r
\r
some use cases:\r
- select a brush\r
- bring up surface inspector\r
- check we had the debug messages from CSurfaceUndo (initialise, activate, snapshot)\r
- edit the surface settings\r
- check the views are updating correctly\r
- hit Ok\r
- check we had a deactivate message\r
OK\r
\r
- select a brush\r
- bring up surface inspector\r
- check we had the debug messages from CSurfaceUndo (initialise, activate, snapshot)\r
- edit the surface settings\r
- check the views are updating correctly\r
- hit cancel / escape\r
- check we have a undo and deactivate from CSurfaceUndo\r
OK\r
\r
- select a brush\r
- bring up the surface inspector\r
- edit the surface settings\r
- hit apply\r
- edit them again\r
- hit cancel / escape\r
- check you get back to the apply state\r
OK\r
\r
- make two brushes\r
- select a brush\r
- bring up surface inspector\r
- change settings\r
- select an additional brush\r
- check the surface inspector, new snapshot\r
- hit cancel\r
- check brushes remained in the same state\r
- use standard Undo\r
- check the first brush got back to it's initial settings\r
OK\r
\r
- select a brush\r
- bring up surface inspector\r
- change settings\r
- select an additional brush\r
- check the surface inspector, new snapshot\r
- change more settings\r
- hit cancel\r
- check the first brush returned to intermediate state, and second to initial state (i.e. last snapshot)\r
OK\r
\r
g_surfaceUndo acts as a layer on top of the core Undo code when the surface inspector is activated.\r
We need it because the surface inspector can edit faces which are not handled by the undo?\r
(or does the current code push the whole brush when editing a face?)\r
\r
not sure of the utility of the g_surfaceDialog hooks here ..\r
default undo usage in the sruface inspector sends way too many undo messages.\r
with the new scheme we store in undo only when select/deselect or user hits apply\r
that way the 'Cancel' and later Ctrl+Z calls make sense\r
but is it worth implementing a new class to achieve that?? .. yes because we intend a later cleanup\r
of this part. (ahem is this reason good enough..)\r
this part is actually much closer from the undo code than I had expected..\r
'Cancel' call being an Undo call..\r
\r
going to Inspector3:\r
don't create a new class, simply use the Undo more intelligently?\r
i.e. don't create undo stuff when editing the brush\r
-> we add a flag to turn off the default undo behaviour and force Undo storage when we want\r
we could also store the undo Id we are interested in and call undo several times to get it back\r
\r
NOTE: what happens if the user hits undo when the surface inspector is up?\r
-> we'll have to take his request into account?\r
err .. performing which undo? The texture positioning or something else?\r
seems the snapshot approach would still make sense then?\r
\r
more use cases, see with Undo calls and select/deselect events\r
NOTE: this whole thing is probably a single call to select_settexture that needs to be turned on/off\r
instead of working at the undo level. but we would like to move to messaging so maybe it still makes sense\r
the undo call is in Select_SetTexture (which does not have that many callers, I was expecting more)\r
\r
the question about having the undo code keep working when surface inspector is around is still raised.\r
but it makes it a lot harder, gotta have a real inspector mode in the undo?\r
dunno, think about it again later\r
\r
two operations are mixed in a single one and should not be:\r
reading the map to get the current data we'll manipulate\r
feed it in the dialog box widgets\r
WARNING: when putting stuff in the widgets, it raises a shitload of update messages and therefor completely\r
fucks up our OnOK OnApply OnCancel scheme (specially OnApply!)\r
\r
NOTE: we want to switch between Surface inspector for brushes only and Patch inspector for patches only\r
there's some crappy code in the surface inspector that we need to get rid of\r
but need to check about that before with Spog or others\r
\r
Forcing the way into using the surface inspector is SCREWED?\r
Doesn't seem to work the way we want to. Always get parasite Undo messages and stuff.\r
We could use a seperate stack for Undo with the surface inspector?\r
Just store the surface properties in a seperate stack?\r
When user hits cancel you go back and apply whatever you had?\r
Doesn't seem like a clean way either.\r
\r
Now dealing with both regular surface inspector and patch inspector:\r
we have some stuff that needs to be on/off with the two inspectors\r
what about catching the messages and issuing new snapshots?\r
the main surface inspector is doing it?\r
no!\r
so what, we have several states?\r
FUCKED UP\r
\r
INSPECTOR 5 ----------------------------------------------------------------\r
restarted from scratch, made much more simple changes.\r
trying another trick for undo (!)\r
just let the undo work as usual, but call undo ourselves in SetTexMods if we have create the last do\r
requires proper initialization/deinitialisation.. in SetTexMods and GetTexMods..\r
\r
getting rid of patch manipulation code in the regular surface inspector. The buttons will \r
still work, but manip will require the patch inspector. (seems the patch inspector doesn't have that\r
much success anyway)\r
\r
TODO:\r
OK get rid of patch stuff\r
OK get rid of the texture toolbar? (it's broken right now)\r
  (and doesn't have anything usefull..)\r
OK (Partial) OnCancel? we need to cancel the texdef as well\r
  store an undo texdef each time we grab new texdef stuff\r
  this works in reverse than the Undo code? When we do the initial\r
  problem is, in some cases the settings that show up are not in sync with what's in the inspector??\r
  (we can't avoid that because if a brush is selected there's no single setting)\r
  prolly get it out as is and let Spog or others send feedback about what it's supposed to do..\r
  for now: store stuff in the cancel texdef when we initialize an undo loop\r
  revert to that if OnCancel is used\r
OK message when spinning over a patch?\r
DUPLICATE (.. see below ..) check the increments we store in the SI are used when shift + arrows etc.\r
  no it doesn't work .. the shifting on keyboard shortcuts is done with m_nTextureTweak\r
  seems m_nTextureTweak is nowhere available in the prefs (and it's not in MFC builds either)\r
  some cleanup to be done around that it seems\r
OK (.. merged with below, maybe some special cases left ..) texture widget (catch the Enter key to force-call an OnApply)\r
OK (.. see above ..) catch Enter key at dialog level to call OnDone\r
NO (.. it's clean, but thats too many lines of code ..) move the code that blokes updates to use gtk_signal_handler_block_by_func and gtk_signal_handler_block_by_func\r
OK shift + arrow must match the SI settings, \r
OK (FIXME .. not using the right scale (using the scale step instead! + add a button in SI to 'Match grid')\r
POSTPONED (.. m_nTextureTweak is used in the nudge commands ..\r
           .. and nudge shortcuts are broken right now ..) get rid of m_nTextureTweak\r
+ SI and PI always on top!\r
\r
+ known issues: "Match Grid" is broken in BP mode\r
\r
now on the patch inspector (nightmare!):\r
OK (.. put it as readonly .. don't bother ..) texture name widget is screwed?\r
OK the spinners scheme doesn't work, the stuff in the dialog is the inc step and we just need arrows\r
OK get rid of the 'Type' dialog box\r
POSTPONED (.. can't do undo on PI without proper Undo module ..) add proper Done Apply Cancel with Undo\r
NO (.. too much work for something that sucks ..) make the changes reflect in the views when manipulating the entries\r
OK (.. using %g ..) cut down on the number of digits!\r
OK increment steps to be stored in the registry\r
\r
putting the Cancel stuff in the surface inspector: only based on the Undo code, no cancel settings to store\r
because we don't have actual storage of a current texdef (we only send alterations) BTW we should do that for \r
brushes as well\r
the patch inspector works by increments, Patch_SetTextureInfo to incrementally modify the patch.\r
we can still do some undo by having a texdef storing the changes and working together with the undo\r
if the undo is recognized, it means our current texdef increment is valid\r
no, we can't represent the combination of several increments scale and rotate in a single texdef..\r
get rid of the undo code for now .. only Apply and Done left\r
\r
it seems it's still vastly broken when you select something. or is it on linux only?\r
need a LOT of testing and figuring it out!!\r
selecting a brush breaks totally.. (the texture screws up it seems)\r
does it attempt to change the texture of the selected object??\r
also: it seems you can multiple select a same brush??\r
\r
the UNDO code of the SURFACE INSPECTOR IS STILL BROKEN ????\r
(ok I'm really screwed, time to sleep)\r
-> can't reproduce now?? maybe it's linux specific problem, I can't tell\r
\r
FOUND A WAY TO REPRODUCE THE CRASH:\r
+ select brush\r
+ hit "Fit"\r
+ hit the shift spinners two times\r
OR:\r
+ select single face on brush\r
+ manually edit scale values\r
-> maybe we have a problem with current texture? (NO)\r
it's some kind of infinite loop? we call UpdateSurfaceInspector from Select_Brush and bang!\r
no, it's a texdef from a face that got deleted\r
prolly that hooking the undo code in there screws up the selected faces stuff\r
if you undo a selected face operation, you end up with the whole brush selected.\r
but that does not necessarily explain why you remove the face at Undo_Start\r
ho well .. removed the undo buffering when selected faces and everything's better\r
would need to re-establish the right face selection after undo, might solve the problem\r
(actually you'd still need to have the settings point to the right object)\r
\r
From PJ about the 'Match Grid' stuff: textures are moved in pixels, not units.\r
We must rely on the current texture scale AND gridsize to compute the shift increment\r