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