more eol-style
[xonotic/netradiant.git] / docs / developer / Inspector / inspector.txt
1 OK. Again I would have liked to get a design document before it being done. Main functionalities we
2 need in the inspector:
3
4 - Unifiy the inspector under a single dialog box, called with 'S'
5
6 - Depending on what is currently selected, display several frames in the inspector:
7 only brushes -> surface inspector
8 only patches -> patch inspector
9 brushes & patches -> both
10 and later when brush primitives are mixed with regular brushes + plugin entities, raise whatever
11 additional inspector stuff we need
12
13 - The camera view must update realtime when we change some parameters.
14
15 - Get rid of the Apply button, use the Undo code to store settings when surface inspector is
16 raised. If user hits Cancel, call the undo stuff.
17
18 - Use the message broadcasting stuff to keep the inspectors up to date when the user changes the
19 current selection. Be careful to keep the undo stuff in sync with the select / deselect operations.
20
21 - Use a 3-state scheme to display the params in the widgets. If two faces are selected that don't
22 have the same shift increment, just grey out the shift box.
23
24 Messaging:
25 - a good chunk of the work is moving the selection/creation stuff to the messaging API
26   we no longer use UpdateSurfaceDialog, we post messages instead ..
27   the surface inspector has hooked one of it's listeners into the corresponding message
28   we may need to reorganize the messages, maybe introduce a hierarchy? 
29   or pass a void * param with messages?
30
31 - we don't post messages like "update surface inspector", we post messages that say "this and that
32 have changed", then the surface inspector reacts if it needs to.
33 Do we need marshalling in the messages? Very likely .. maybe using Gtk signal stuff would be interesting?
34
35 -> the messaging stuff is a big chunk of work and our surface inspector changes are not totally 
36 dependent on it. Better leave that for l8r
37
38 the inspector works by states and transitions? Or we post messages to it?
39 Use case:
40 the user raises the inspector .. if we are up we'll ignore, if we are hidden we'll
41 go through the whole process (initialise, look at what is selected, display)
42 then we enter an active state (listening for select / deselects and applying stuff)
43
44 all in all it seems to be too big a change for next release. will see later probably.
45 Trying a few more days with it, see what happens. after all the interface is fairly restricted
46 so there's a good chance our changes are fairly stable in the end. But rebuilding the whole interface
47 part might be too much ...
48 We need something state based? AND a set of messages ..
49 but first, need to write the initialisation loop
50 build the dialog, get the current surface information and display
51
52 Undoing the changes on the selected stuff:
53 at any point in time, one can get a snapshot of selected stuff and use it to store the surface
54 properties settings for later on. But what happens if the user modifies the selected brush, pushing
55 it in the undo stack? Then we would cancel the changes? (and just backup to the state right after
56 the modif)
57 We could has the 'Apply' button used for that .. grey it out when the current state is the one in
58 the backup. This happens whenever we hit 'Apply' or change something in the selection.
59 The selection has several items: entities, brushes and selected faces (possibly later generic plugin entities)
60 Current undo stuff is aimed at entities and brushes.
61 NOTE: you can't have selected faces and brushes/entities at the same time, that's a good point to
62 keep that seperated to deal with undo and storage
63 On what side should the implemetation be ? undo.cpp select.cpp or surfacedialog.cpp ?
64 We are going to do it with the messaging API anyway..
65 And hook in the undo stuff, to reset the snapshot each time something gets pushed in the undo?
66
67 We have advanced stuff on the Inspector branch, doing basics on Alpha branch.
68 Start writing the watch code in surfacedialog.cpp, see if we need some merging with Undo stuff l8r
69 We need to track for the patch inspector as well..
70
71 basic code for CSurfaceUndo written. need to add hooks for the snapshot stuff and undo stuff. and a
72 debug flag to monitor the life cycle of the object.
73
74 some use cases:
75 - select a brush
76 - bring up surface inspector
77 - check we had the debug messages from CSurfaceUndo (initialise, activate, snapshot)
78 - edit the surface settings
79 - check the views are updating correctly
80 - hit Ok
81 - check we had a deactivate message
82 OK
83
84 - select a brush
85 - bring up surface inspector
86 - check we had the debug messages from CSurfaceUndo (initialise, activate, snapshot)
87 - edit the surface settings
88 - check the views are updating correctly
89 - hit cancel / escape
90 - check we have a undo and deactivate from CSurfaceUndo
91 OK
92
93 - select a brush
94 - bring up the surface inspector
95 - edit the surface settings
96 - hit apply
97 - edit them again
98 - hit cancel / escape
99 - check you get back to the apply state
100 OK
101
102 - make two brushes
103 - select a brush
104 - bring up surface inspector
105 - change settings
106 - select an additional brush
107 - check the surface inspector, new snapshot
108 - hit cancel
109 - check brushes remained in the same state
110 - use standard Undo
111 - check the first brush got back to it's initial settings
112 OK
113
114 - select a brush
115 - bring up surface inspector
116 - change settings
117 - select an additional brush
118 - check the surface inspector, new snapshot
119 - change more settings
120 - hit cancel
121 - check the first brush returned to intermediate state, and second to initial state (i.e. last snapshot)
122 OK
123
124 g_surfaceUndo acts as a layer on top of the core Undo code when the surface inspector is activated.
125 We need it because the surface inspector can edit faces which are not handled by the undo?
126 (or does the current code push the whole brush when editing a face?)
127
128 not sure of the utility of the g_surfaceDialog hooks here ..
129 default undo usage in the sruface inspector sends way too many undo messages.
130 with the new scheme we store in undo only when select/deselect or user hits apply
131 that way the 'Cancel' and later Ctrl+Z calls make sense
132 but is it worth implementing a new class to achieve that?? .. yes because we intend a later cleanup
133 of this part. (ahem is this reason good enough..)
134 this part is actually much closer from the undo code than I had expected..
135 'Cancel' call being an Undo call..
136
137 going to Inspector3:
138 don't create a new class, simply use the Undo more intelligently?
139 i.e. don't create undo stuff when editing the brush
140 -> we add a flag to turn off the default undo behaviour and force Undo storage when we want
141 we could also store the undo Id we are interested in and call undo several times to get it back
142
143 NOTE: what happens if the user hits undo when the surface inspector is up?
144 -> we'll have to take his request into account?
145 err .. performing which undo? The texture positioning or something else?
146 seems the snapshot approach would still make sense then?
147
148 more use cases, see with Undo calls and select/deselect events
149 NOTE: this whole thing is probably a single call to select_settexture that needs to be turned on/off
150 instead of working at the undo level. but we would like to move to messaging so maybe it still makes sense
151 the undo call is in Select_SetTexture (which does not have that many callers, I was expecting more)
152
153 the question about having the undo code keep working when surface inspector is around is still raised.
154 but it makes it a lot harder, gotta have a real inspector mode in the undo?
155 dunno, think about it again later
156
157 two operations are mixed in a single one and should not be:
158 reading the map to get the current data we'll manipulate
159 feed it in the dialog box widgets
160 WARNING: when putting stuff in the widgets, it raises a shitload of update messages and therefor completely
161 fucks up our OnOK OnApply OnCancel scheme (specially OnApply!)
162
163 NOTE: we want to switch between Surface inspector for brushes only and Patch inspector for patches only
164 there's some crappy code in the surface inspector that we need to get rid of
165 but need to check about that before with Spog or others
166
167 Forcing the way into using the surface inspector is SCREWED?
168 Doesn't seem to work the way we want to. Always get parasite Undo messages and stuff.
169 We could use a seperate stack for Undo with the surface inspector?
170 Just store the surface properties in a seperate stack?
171 When user hits cancel you go back and apply whatever you had?
172 Doesn't seem like a clean way either.
173
174 Now dealing with both regular surface inspector and patch inspector:
175 we have some stuff that needs to be on/off with the two inspectors
176 what about catching the messages and issuing new snapshots?
177 the main surface inspector is doing it?
178 no!
179 so what, we have several states?
180 FUCKED UP
181
182 INSPECTOR 5 ----------------------------------------------------------------
183 restarted from scratch, made much more simple changes.
184 trying another trick for undo (!)
185 just let the undo work as usual, but call undo ourselves in SetTexMods if we have create the last do
186 requires proper initialization/deinitialisation.. in SetTexMods and GetTexMods..
187
188 getting rid of patch manipulation code in the regular surface inspector. The buttons will 
189 still work, but manip will require the patch inspector. (seems the patch inspector doesn't have that
190 much success anyway)
191
192 TODO:
193 OK get rid of patch stuff
194 OK get rid of the texture toolbar? (it's broken right now)
195   (and doesn't have anything usefull..)
196 OK (Partial) OnCancel? we need to cancel the texdef as well
197   store an undo texdef each time we grab new texdef stuff
198   this works in reverse than the Undo code? When we do the initial
199   problem is, in some cases the settings that show up are not in sync with what's in the inspector??
200   (we can't avoid that because if a brush is selected there's no single setting)
201   prolly get it out as is and let Spog or others send feedback about what it's supposed to do..
202   for now: store stuff in the cancel texdef when we initialize an undo loop
203   revert to that if OnCancel is used
204 OK message when spinning over a patch?
205 DUPLICATE (.. see below ..) check the increments we store in the SI are used when shift + arrows etc.
206   no it doesn't work .. the shifting on keyboard shortcuts is done with m_nTextureTweak
207   seems m_nTextureTweak is nowhere available in the prefs (and it's not in MFC builds either)
208   some cleanup to be done around that it seems
209 OK (.. merged with below, maybe some special cases left ..) texture widget (catch the Enter key to force-call an OnApply)
210 OK (.. see above ..) catch Enter key at dialog level to call OnDone
211 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
212 OK shift + arrow must match the SI settings, 
213 OK (FIXME .. not using the right scale (using the scale step instead! + add a button in SI to 'Match grid')
214 POSTPONED (.. m_nTextureTweak is used in the nudge commands ..
215            .. and nudge shortcuts are broken right now ..) get rid of m_nTextureTweak
216 + SI and PI always on top!
217
218 + known issues: "Match Grid" is broken in BP mode
219
220 now on the patch inspector (nightmare!):
221 OK (.. put it as readonly .. don't bother ..) texture name widget is screwed?
222 OK the spinners scheme doesn't work, the stuff in the dialog is the inc step and we just need arrows
223 OK get rid of the 'Type' dialog box
224 POSTPONED (.. can't do undo on PI without proper Undo module ..) add proper Done Apply Cancel with Undo
225 NO (.. too much work for something that sucks ..) make the changes reflect in the views when manipulating the entries
226 OK (.. using %g ..) cut down on the number of digits!
227 OK increment steps to be stored in the registry
228
229 putting the Cancel stuff in the surface inspector: only based on the Undo code, no cancel settings to store
230 because we don't have actual storage of a current texdef (we only send alterations) BTW we should do that for 
231 brushes as well
232 the patch inspector works by increments, Patch_SetTextureInfo to incrementally modify the patch.
233 we can still do some undo by having a texdef storing the changes and working together with the undo
234 if the undo is recognized, it means our current texdef increment is valid
235 no, we can't represent the combination of several increments scale and rotate in a single texdef..
236 get rid of the undo code for now .. only Apply and Done left
237
238 it seems it's still vastly broken when you select something. or is it on linux only?
239 need a LOT of testing and figuring it out!!
240 selecting a brush breaks totally.. (the texture screws up it seems)
241 does it attempt to change the texture of the selected object??
242 also: it seems you can multiple select a same brush??
243
244 the UNDO code of the SURFACE INSPECTOR IS STILL BROKEN ????
245 (ok I'm really screwed, time to sleep)
246 -> can't reproduce now?? maybe it's linux specific problem, I can't tell
247
248 FOUND A WAY TO REPRODUCE THE CRASH:
249 + select brush
250 + hit "Fit"
251 + hit the shift spinners two times
252 OR:
253 + select single face on brush
254 + manually edit scale values
255 -> maybe we have a problem with current texture? (NO)
256 it's some kind of infinite loop? we call UpdateSurfaceInspector from Select_Brush and bang!
257 no, it's a texdef from a face that got deleted
258 prolly that hooking the undo code in there screws up the selected faces stuff
259 if you undo a selected face operation, you end up with the whole brush selected.
260 but that does not necessarily explain why you remove the face at Undo_Start
261 ho well .. removed the undo buffering when selected faces and everything's better
262 would need to re-establish the right face selection after undo, might solve the problem
263 (actually you'd still need to have the settings point to the right object)
264
265 From PJ about the 'Match Grid' stuff: textures are moved in pixels, not units.
266 We must rely on the current texture scale AND gridsize to compute the shift increment